shaf 1.6.0 → 3.0.0

data/lib/shaf/profile/unique_id.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Shaf
+  class Profile
+    module UniqueId
+      def id
+        return @id if defined? @id
+        @id = __find_unique_id
+      end
+
+      def __pending_id?
+        @__pending_id ||= false
+      end
+
+      private
+
+      def __find_unique_id
+        @__pending_id = true
+
+        return name.to_s unless __id_collision? name.to_s
+
+        id = [parent.name, name].join('_')
+        return id unless __id_collision? id
+
+        id = "#{id}0"
+
+        loop do
+          id = id.next
+          break id unless __id_collision? id
+        end
+      ensure
+        @__pending_id = false
+      end
+
+      def __id_collision? id
+        descriptor = self
+
+        loop do
+          break false unless descriptor.respond_to?(:parent) && descriptor.parent
+          descriptor = descriptor.parent
+
+          __parent_descriptors(descriptor).each do |desc|
+            next if desc == self
+            next if desc.__pending_id?
+            return true if desc.id == id
+          end
+        end
+      end
+
+      def __parent_descriptors(parent)
+        descriptors = []
+        descriptors += parent.attributes if parent.respond_to? :attributes
+        descriptors += parent.relations if parent.respond_to? :relations
+        descriptors
+      end
+    end
+  end
+end

data/lib/shaf/profile.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'shaf/profile/evaluator'
+require 'shaf/extensions/resource_uris'
+
+module Shaf
+  class Profile
+    module NormalizeName
+      private def normalize(name)
+        name.to_s.downcase.tr('-', '_')
+      end
+    end
+
+    extend NormalizeName
+    include NormalizeName
+    include Shaf::UriHelper
+
+    class << self
+      def inherited(child)
+        Profiles.register child
+      end
+
+      def name(str = nil)
+        @name = str if str
+        @name if defined? @name
+      end
+
+      def doc(str = nil)
+        @doc = str if str
+        @doc if defined? @doc
+      end
+
+      def urn(value = nil)
+        @urn = value if value
+        @urn if defined? @urn
+      end
+
+      def example(str)
+        examples << str
+      end
+
+      def match?(str)
+        normalize(name) == normalize(str)
+      end
+
+      def attributes
+        @attributes ||= []
+      end
+
+      def relations
+        @relations ||= []
+      end
+
+      def examples
+        @examples ||= []
+      end
+
+      def attribute(*args, **kwargs, &block)
+        evaluator.attribute(*args, **kwargs, &block)
+      end
+
+      def relation(*args, **kwargs, &block)
+        evaluator.rel(*args, **kwargs, &block)
+      end
+      alias rel relation
+
+      def descriptor(id)
+        find_attribute(id) || find_relation(id)
+      end
+
+      def find_attribute(id)
+        attributes.find { |attr| attr.id.to_sym == id.to_sym }
+      end
+
+      def find_relation(id)
+        relations.find { |rel| rel.id.to_sym == id.to_sym }
+      end
+
+      def use(*descriptors, from:, doc: nil)
+        descriptors.each do |id|
+          desc = from.descriptor(id)
+          href = profile_path(from.name, fragment_id: id)
+
+          case desc
+          when Relation
+            kwargs = {
+              doc: doc || desc&.doc,
+              href: href,
+              http_methods: desc.http_methods,
+              payload_type: desc.payload_type,
+              content_type: desc.content_type,
+            }
+            relation(id, **kwargs)
+          when Attribute
+            attribute(id, href: href, doc: doc)
+          when NilClass
+            raise "#{from.name} does not have a descriptor with id #{id}"
+          else
+            raise Errors::ServerError, "Unsupported descriptor: #{desc}"
+          end
+        end
+      end
+
+      private
+
+      def evaluator
+        Evaluator.new(parent: self)
+      end
+    end
+
+    def name
+      normalize(self.class.name)
+    end
+  end
+end

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/profiles.rb

@@ -0,0 +1,46 @@
+require 'shaf/errors'
+
+module Shaf
+  module Profiles
+    class ProfileNotFoundError < Errors::NotFoundError
+      def initialize(name)
+        msg = %Q(Profile with name "#{name}" does not exist)
+        super(msg, id: name)
+      end
+    end
+
+    class << self
+      def register(clazz)
+        profiles << clazz
+      end
+
+      def unregister(clazz)
+        profiles.delete(clazz)
+      end
+
+      def find(name)
+        name = String(name)
+        return if name.empty?
+
+        profiles.find { |profile| profile.match? name }
+      end
+
+      def find!(name)
+        find(name) or raise ProfileNotFoundError, name
+      end
+
+      def profiles
+        @profiles ||= []
+      end
+
+      def clear
+        @profiles.clear
+      end
+    end
+  end
+end
+
+require 'shaf/profile'
+require 'shaf/profiles/shaf_form'
+require 'shaf/profiles/shaf_error'
+require 'shaf/profiles/shaf_basic'

data/lib/shaf/registrable_factory.rb

@@ -1,15 +1,58 @@
 module Shaf
   module RegistrableFactory
-
     class NotFoundError < StandardError; end
+    class NoIdentifiersError < StandardError
+
+      def initialize(clazz)
+        super <<~ERR
+          #{clazz} does not have an @identifiers ivar.
+          Did you perhaps forget to call `#{clazz}.identifier`?
+        ERR
+      end
+    end
+
+    class Entry
+      attr_reader :clazz
+
+      def initialize(clazz)
+        @clazz = clazz
+      end
+
+      def match?(strings)
+        raise NoIdentifiersError, clazz unless identifiers
+        return false if strings.size < identifiers.size
+        identifiers.zip(strings).all? { |pattern, str| matching_identifier? str, pattern }
+      end
+
+      def identifier_count
+        identifiers&.size || 0
+      end
+
+      def usage
+        clazz.instance_variable_get(:@usage)
+      end
+
+      private
+
+      def identifiers
+        clazz.identified_by
+      end
+
+      def matching_identifier?(str, pattern)
+        return false if pattern.nil? || str.nil? || str.empty?
+        pattern = pattern.to_s if pattern.is_a? Symbol
+        return str == pattern if pattern.is_a? String
+        !!str.match(pattern)
+      end
+    end
 
     def all
-      reg.dup
+      reg.map(&:clazz)
     end
 
-    def each
+    def each(&block)
       return all.each unless block_given?
-      all.each { |c| yield c }
+      all.each(&block)
     end
 
     def size
@@ -17,34 +60,31 @@ module Shaf
     end
 
     def register(clazz)
-      reg << clazz
+      reg << Entry.new(clazz)
     end
 
     def unregister(*str)
       return if str.empty? || !str.all?
-      reg.delete_if { |clazz| matching_class? str, clazz }
+      reg.delete_if { |entry| entry.match? str }
     end
 
     def lookup(*str)
-      return if str.empty? || !str.all?
-      reg.select { |clazz| matching_class? str, clazz }
-        .sort_by(&method(:identifier_count))
-        .last
+      lookup_entry(*str)&.clazz
     end
 
     def usage
       reg.compact.map do |entry|
-        usage = entry.instance_variable_get(:@usage)
+        usage = entry.usage
         usage.respond_to?(:call) ? usage.call : usage
       end
     end
 
     def create(*params, **options)
-      clazz = lookup(*params)
-      raise NotFoundError.new(%Q(Command '#{ARGV}' is not supported)) unless clazz
+      entry = lookup_entry(*params)
+      raise NotFoundError.new(%Q(Command '#{ARGV}' is not supported)) unless entry
 
-      args = init_args(clazz, params)
-      clazz.new(*args, **options)
+      args = init_args(entry, params)
+      entry.clazz.new(*args, **options)
     end
 
     private
@@ -53,25 +93,15 @@ module Shaf
       @reg ||= []
     end
 
-    def matching_class?(strings, clazz)
-      identifiers = clazz.instance_variable_get(:@identifiers)
-      return false if strings.size < identifiers.size
-      identifiers.zip(strings).all? { |pattern, str| matching_identifier? str, pattern }
-    end
-
-    def matching_identifier?(str, pattern)
-      return false if pattern.nil? || str.nil? || str.empty?
-      pattern = pattern.to_s if pattern.is_a? Symbol
-      return str == pattern if pattern.is_a? String
-      str.match(pattern) || false
-    end
-
-    def identifier_count(clazz)
-      clazz.instance_variable_get(:@identifiers)&.size || 0
+    def lookup_entry(*str)
+      return if str.empty? || !str.all?
+      reg.select { |entry| entry.match? str }
+        .sort_by { |entry| entry.identifier_count }
+        .last
     end
 
-    def init_args(clazz, params)
-      first_non_id = identifier_count(clazz)
+    def init_args(entry, params)
+      first_non_id = entry.identifier_count
       params[first_non_id..-1]
     end
   end

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