shaf 1.6.1 → 2.0.0

data/lib/shaf/profile.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'shaf/profile/evaluator'
+require 'shaf/extensions/resource_uris'
+
+module Shaf
+  class Profile
+    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 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
+
+      def normalize(name)
+        name.to_s.downcase.tr('-', '_')
+      end
+    end
+
+    def name
+      normalize(self.class.name)
+    end
+
+    def normalize(str)
+      self.class.normalize(str)
+    end
+  end
+end

data/lib/shaf/profile/attribute.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'shaf/profile/unique_id'
+
+module Shaf
+  class Profile
+    class Attribute
+      include UniqueId
+
+      attr_reader :name, :doc, :href, :type, :parent
+
+      def initialize(name, **opts)
+        @name = name.to_sym
+        @doc = opts[:doc].freeze
+        @href = opts[:href].freeze
+        @type = opts[:type]&.to_s
+        @parent = opts[:parent]
+      end
+
+      def attributes
+        @attributes ||= []
+      end
+
+      def relations
+        @relations ||= []
+      end
+    end
+  end
+end

data/lib/shaf/profile/evaluator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'shaf/profile/attribute'
+require 'shaf/profile/relation'
+
+module Shaf
+  class Profile
+    class Evaluator
+      attr_reader :parent, :allowed
+
+      def initialize(parent:, allowed: nil)
+        @parent = parent
+        @allowed = allowed && Array(allowed).map(&:to_sym)
+      end
+
+      def attribute(name, doc:, type: :string, &block)
+        return unless allow? :attribute
+
+        attr = Attribute.new(name, doc: doc, type: type, parent: parent)
+        self.class.new(parent: attr, allowed: allowed).instance_exec(&block) if block
+        parent.attributes << attr
+      end
+
+      def relation(name, **kwargs, &block)
+        return unless allow? :rel
+
+        rel = Relation.new(name, parent: parent, **kwargs)
+        self.class.new(parent: rel, allowed: [:attribute]).instance_exec(&block) if block
+        parent.relations << rel
+      end
+      alias rel relation
+
+      private
+
+      def allow?(name)
+        return true unless allowed
+        return true if allowed.include? name
+
+        Shaf.log.warn "#{name} is not allowed to be nested inside #{parent.class} " \
+          "(or parent object containing #{parent.class})"
+
+        false
+      end
+    end
+  end
+end

data/lib/shaf/profile/relation.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'shaf/profile/unique_id'
+
+module Shaf
+  class Profile
+    class Relation
+      include UniqueId
+
+      attr_reader :name, :doc, :href, :http_methods, :payload_type, :content_type, :parent
+
+      def initialize(name, **opts)
+        @name = name.to_sym
+        @doc = opts[:doc].freeze
+        @href = opts[:href].freeze
+        http_methods = Array(opts[:http_method]) + Array(opts[:http_methods])
+        http_methods  << 'GET' if http_methods.empty?
+        @http_methods = http_methods.map { |m| m.to_s.upcase }.uniq.freeze
+        @payload_type = opts[:payload_type].freeze
+        @content_type = opts[:content_type].freeze
+        @parent = opts[:parent]
+      end
+
+      def attributes
+        @attributes ||= []
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+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 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/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,48 @@
+# frozen_string_literal: true
+
+module Shaf
+  module Profiles
+    class ShafError < Shaf::Profile
+      name '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,109 @@
+# frozen_string_literal: true
+
+module Shaf
+  module Profiles
+    class ShafForm < Shaf::Profile
+      name '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