shaf_client 0.6.1 → 1.0.0

data/lib/shaf_client/content_type_map.rb

@@ -0,0 +1,53 @@
+require 'forwardable'
+
+class ShafClient
+  class ContentTypeMap
+    extend Forwardable
+
+    def_delegators :@map, :default, :default=, :keys, :values, :each
+
+    def initialize
+      @map = {}
+    end
+
+    def [](content_type, profile = nil)
+      key = key_for(content_type, profile)
+      map.fetch(key) do
+        key = key_for(content_type, nil)
+        map[key]
+      end
+    end
+
+    def []=(content_type, profile = nil, value)
+      key = key_for(content_type, profile)
+      map[key] = value
+    end
+
+    def key?(content_type, profile = nil)
+      key = key_for(content_type, profile)
+      map.key? key
+    end
+
+    def delete(content_type, profile = nil)
+      key = key_for(content_type, profile)
+      map.delete(key)
+    end
+
+    def key_for(content_type, profile)
+      return unless content_type
+
+      key = content_type.to_s.downcase
+      key = strip_parameters(key)
+      key << "_#{profile.to_s.downcase}" if profile
+      key
+    end
+
+    private
+
+    attr_reader :map
+
+    def strip_parameters(content_type)
+      content_type&.sub(/;.*/, '')
+    end
+  end
+end

data/lib/shaf_client/curie.rb

@@ -26,5 +26,9 @@ class ShafClient
       args[:rel] &&= args[:rel].to_s.sub(/#{name}:/, '')
       super(**args)
     end
+
+    def to_h
+      {name: name}.merge(super)
+    end
   end
 end

data/lib/shaf_client/empty_resource.rb

@@ -21,7 +21,7 @@ class ShafClient
 
     %i[get put post delete patch, get_doc, reload!].each do |method|
       define_method(method) do |*_args|
-        raise "EmptyResource: #{method} not available"
+        raise Error, "EmptyResource: #{method} not available"
       end
     end
   end

data/lib/shaf_client/hal_form.rb

@@ -24,7 +24,7 @@ class ShafClient
 
     def fields
       template[:properties].map do |values|
-        Field.new(values.transform_keys(&:to_sym))
+        Field.new(**values.transform_keys(&:to_sym))
       end
     end
 

data/lib/shaf_client/hypertext_cache_strategy.rb

@@ -0,0 +1,43 @@
+class ShafClient
+  module HypertextCacheStrategy
+    AVAILABLE_CACHE_STRATEGIES = [
+      CACHE_STRATEGY_NO_CACHE = :no_cache,
+      CACHE_STRATEGY_EMBEDDED = :use_embedded,
+      CACHE_STRATEGY_FETCH_HEADERS = :fetch_headers
+    ]
+
+    class << self
+      def cacheable?(strategy)
+        [CACHE_STRATEGY_EMBEDDED, CACHE_STRATEGY_FETCH_HEADERS].include? strategy
+      end
+
+      def fetch_headers?(strategy)
+        CACHE_STRATEGY_FETCH_HEADERS == strategy
+      end
+
+      def default_http_status
+        203
+      end
+    end
+
+    def default_hypertext_cache_strategy
+      @__default_hypertext_cache_strategy ||= CACHE_STRATEGY_EMBEDDED
+    end
+
+    def default_hypertext_cache_strategy=(strategy)
+      unless __valid_cache? strategy
+        raise Error, <<~ERR
+          Unsupported hypertext cache strategy: #{strategy}
+          Possible strategies are: #{AVAILABLE_CACHE_STRATEGIES.join(', ')}
+        ERR
+      end
+      @__default_hypertext_cache_strategy = value
+    end
+
+    private
+
+    def __valid_cache?(strategy)
+      AVAILABLE_CACHE_STRATEGIES.include? strategy
+    end
+  end
+end

data/lib/shaf_client/link.rb

@@ -27,8 +27,8 @@ class ShafClient
       return href unless templated?
 
       href
-        .then { |href| resolve_required(href, **args) }
-        .then { |href| resolve_optional(href, **args) }
+        .yield_self { |href| resolve_required(href, **args) }
+        .yield_self { |href| resolve_optional(href, **args) }
     end
 
     def to_h

data/lib/shaf_client/mime_types.rb

@@ -0,0 +1,8 @@
+class ShafClient
+  module MimeTypes
+    MIME_TYPE_JSON = 'application/json'
+    MIME_TYPE_HAL  = 'application/hal+json'
+    MIME_TYPE_PROBLEM_JSON  = 'application/problem+json'
+    MIME_TYPE_ALPS_JSON  = 'application/alps+json'
+  end
+end

data/lib/shaf_client/problem_json.rb

@@ -0,0 +1,38 @@
+require 'shaf_client/form'
+require 'shaf_client/status_codes'
+
+class ShafClient
+  class ProblemJson < Resource
+    include StatusCodes
+
+    content_type MIME_TYPE_PROBLEM_JSON
+
+    def type
+      attribute(:type) { 'about:blank' }
+    end
+
+    def title
+      attribute(:title) do
+        next unless type == 'about:blank'
+
+        StatusCode[status] if (400..599).include? status.to_i
+      end
+    end
+
+    def status
+      attribute(:status) { http_status }
+    end
+
+    def detail
+      attribute(:detail)
+    end
+
+    def instance
+      attribute(:instance)
+    end
+
+    def to_h
+      attributes
+    end
+  end
+end

data/lib/shaf_client/resource.rb

@@ -4,21 +4,34 @@ require 'shaf_client/base_resource'
 
 class ShafClient
   class Resource < BaseResource
+    include MimeTypes
+
     attr_reader :http_status, :headers
 
-    ResourceMapper.register("application/hal+json", self)
+    ResourceMapper.register(MIME_TYPE_HAL, self)
 
-    def self.content_type(type)
-      ResourceMapper.register(type, self)
+    def self.content_type(type, profile: nil)
+      ResourceMapper.register(type, profile, self)
     end
 
     def self.profile(name)
-      content_type "application/hal+json;profile=#{name}"
+      content_type MIME_TYPE_HAL, profile: name
+    end
+
+    def self.build(client, payload, content_type = MIME_TYPE_HAL, status = nil, headers = {})
+      resource_class, extensions = ResourceMapper.for(
+        content_type: content_type,
+        headers: headers,
+        payload: payload,
+        client: client,
+      )
+      resrc = resource_class.new(client, payload, status, headers)
+      extensions.compact.each { |extension| resrc.extend extension }
+      resrc
     end
 
-    def self.build(client, payload, status = nil, headers = {})
-      content_type = headers.fetch('content-type', '')
-      ResourceMapper.for(content_type).new(client, payload, status, headers)
+    def self.default_resource_class!
+      ResourceMapper.default = self
     end
 
     def initialize(client, payload, status = nil, headers = {})
@@ -28,14 +41,29 @@ class ShafClient
       super(payload)
     end
 
-    %i[get put post delete patch].each do |method|
+    def inspect
+      <<~RESOURCE
+        Status: #{http_status}
+        Headers: #{headers}
+        #{to_s}
+      RESOURCE
+    end
+
+    %i[put post delete patch].each do |method|
       define_method(method) do |rel, payload = nil, **options|
         href = link(rel).href
         client.send(method, href, payload: payload, **options)
       end
     end
 
-    def get_doc(rel)
+    def get(rel, **options)
+      href = link(rel).href
+      embedded_resource = _embedded(rel)
+      cached_resource = hypertext_cache_resource(href, embedded_resource, options)
+      cached_resource || client.get(href, **options)
+    end
+
+    def get_doc(rel, **options)
       rel = rel.to_s
       curie_name, rel =
         if rel.include? ':'
@@ -46,7 +74,7 @@ class ShafClient
 
       curie = curie(curie_name)
       uri = curie.resolve_templated(rel: rel)
-      client.get_doc(uri)
+      client.get(uri, **options)
     end
 
     def get_hal_form(rel)
@@ -72,9 +100,14 @@ class ShafClient
       delete(:delete)
     end
 
+    def content_type
+      headers['content-type']
+    end
+
     protected
 
     def <<(other)
+      @client       = other.client
       @http_status  = other.http_status.dup
       @headers      = other.headers.dup
       super
@@ -83,5 +116,44 @@ class ShafClient
     private
 
     attr_reader :client
+
+    def build_embedded_resource(payload)
+      self.class.build(
+        client,
+        payload,
+        headers['content-type'],
+        http_status,
+        headers
+      )
+    end
+
+    def hypertext_cache_strategy(options)
+      options.fetch(:hypertext_cache_strategy) do
+        ShafClient.default_hypertext_cache_strategy
+      end
+    end
+
+    def hypertext_cache?(options)
+      HypertextCacheStrategy.cacheable? hypertext_cache_strategy(options)
+    end
+
+    def hypertext_cache_resource(href, embedded_resource, options)
+      return unless embedded_resource
+
+      cache_strategy = hypertext_cache_strategy(options)
+      return unless HypertextCacheStrategy.cacheable? cache_strategy
+
+      if HypertextCacheStrategy.fetch_headers? cache_strategy
+        resource = client.head(href, **options)
+        status = resource.http_status
+        headers = resource.headers
+        embedded_resource = embedded_resource.payload
+      else
+        status = HypertextCacheStrategy.default_http_status
+        headers = embedded_resource.headers
+      end
+
+      self.class.build(client, embedded_resource, headers['content-type'], status, headers)
+    end
   end
 end

data/lib/shaf_client/resource_extension.rb

@@ -0,0 +1,36 @@
+require 'set'
+
+class ShafClient
+  module ResourceExtension
+    class << self
+      def register(extender)
+        extenders << extender
+      end
+
+      def unregister(extender)
+        extenders.delete(extender)
+      end
+
+      def for(profile, base, link_relations, client)
+        link_relations = remove_curies(link_relations)
+        extenders.map { |extender| extender.call(profile, base, link_relations, client) }
+          .compact
+      end
+
+      private
+
+      def extenders
+        @extenders ||= Set.new
+      end
+
+      def remove_curies(link_relations)
+        Array(link_relations).map do |rel|
+          rel.to_s.sub(/[^:]*:/, '').to_sym
+        end
+      end
+    end
+  end
+end
+
+require 'shaf_client/resource_extension/base'
+require 'shaf_client/resource_extension/alps_http_method'

data/lib/shaf_client/resource_extension/alps_http_method.rb

@@ -0,0 +1,67 @@
+class ShafClient
+  module ResourceExtension
+    class AlpsHttpMethod < Base
+      class << self
+        def call(profile, base, link_relations, _client)
+          return unless profile.is_a? AlpsJson
+          return unless base <= Resource
+
+          link_relations = Array(link_relations).compact
+          descriptors = descriptors_with_http_method(profile)
+          descriptors.keep_if do |descriptor|
+            link_relations.include? identifier_for(descriptor)&.to_sym
+          end
+
+          extension_for(descriptors)
+        end
+
+        private
+
+        def descriptors_with_http_method(profile)
+          profile.each_descriptor.each_with_object([]) do |descriptor, descriptors|
+            next unless descriptor.extension(:http_method)
+            descriptors << descriptor
+          end
+        end
+
+        def extension_for(descriptors)
+          return if descriptors.empty?
+
+          Module.new.tap do |mod|
+            descriptors.each do |descriptor|
+              add_method(mod, descriptor, methods.first)
+            end
+          end
+        end
+
+        def add_method(mod, descriptor, method)
+          rel = identifier_for(descriptor)
+          return unless rel
+
+          ext = descriptor.extension(:http_method)
+          methods = Array(ext&.value)
+
+          # We only know what method to use when size is 1
+          return unless methods.size == 1
+
+          http_method = methods.first.downcase.to_sym
+          name = method_name_from(rel)
+
+          mod.define_method(name) do |payload: nil, **options|
+            href = link(rel).href
+            client.send(http_method, href, payload: payload, **options)
+          end
+        end
+
+        def method_name_from(rel)
+          "#{rel.to_s.downcase.tr('-', '_')}!"
+        end
+
+        def identifier_for(descriptor)
+          # Currently we only support `id` (i.e no support for descriptors with `href`)
+          descriptor.id
+        end
+      end
+    end
+  end
+end

data/lib/shaf_client/resource_extension/base.rb

@@ -0,0 +1,13 @@
+class ShafClient
+  module ResourceExtension
+    class Base
+      def self.inherited(mod)
+        ResourceExtension.register(mod)
+      end
+
+      def self.call(*args)
+        raise NotImplementedError, "Class '#{self}' must respond to `call`"
+      end
+    end
+  end
+end