hal_api-rails 0.2.0

data/lib/hal_api/errors.rb

@@ -0,0 +1,32 @@
+require 'roar/json/hal'
+
+module HalApi::Errors
+
+  class ApiError < StandardError
+    attr_accessor :status
+
+    def initialize(message = nil, status = 500)
+      super(message || "API Error")
+      self.status = status
+    end
+  end
+
+  class NotFound < ApiError
+    def initialize(message = nil)
+      super(message || "Resource Not Found", 404)
+    end
+  end
+
+  class UnsupportedMediaType < ApiError
+    def initialize(type)
+      super("Unsupported Media Type '#{type.inspect}'", 415)
+    end
+  end
+
+  module Representer
+    include Roar::JSON::HAL
+
+    property :status
+    property :message
+  end
+end

data/lib/hal_api/paged_collection.rb

@@ -0,0 +1,77 @@
+require 'forwardable'
+require 'openssl'
+require 'active_model'
+
+class HalApi::PagedCollection
+  extend ActiveModel::Naming
+  extend Forwardable
+
+  attr_accessor :items, :request, :options
+
+  def_delegators :items, :total_count, :prev_page, :next_page, :total_pages, :first_page?, :last_page?
+  alias_method :total, :total_count
+
+  def_delegators :request, :params
+
+  def to_model
+    self
+  end
+
+  def persisted?
+    false
+  end
+
+  def initialize(items, request=nil, options=nil)
+    self.items   = items
+    self.request = request || request_stub
+    self.options = options || {}
+    self.options[:is_root_resource] = true unless (self.options[:is_root_resource] == false)
+  end
+
+  def cache_key
+    item_keys = items.inject([]) do |keys, i|
+      keys << i.try(:id)
+      keys << i.try(:updated_at).try(:utc).to_i
+    end
+    key_components = ['c', item_class.model_name.cache_key]
+    key_components << OpenSSL::Digest::MD5.hexdigest(item_keys.join)
+    ActiveSupport::Cache.expand_cache_key(key_components)
+  end
+
+  def request_stub
+    OpenStruct.new(params: {})
+  end
+
+  def is_root_resource
+    !!self.options[:is_root_resource]
+  end
+
+  def show_curies
+    is_root_resource && !options[:no_curies]
+  end
+
+  def item_class
+    options[:item_class] || self.items.first.try(:item_class) || self.items.first.class
+  end
+
+  def item_decorator
+    options[:item_decorator] || "Api::#{item_class.name}Representer".constantize
+  end
+
+  # url to use for the self:href, can be a string or proc
+  def url
+    options[:url]
+  end
+
+  # If this is an embedded collection, the parent will be set here for use in urls
+  def parent
+    rep = options[:parent]
+    return rep unless rep.respond_to?(:becomes)
+    klass = rep.class.try(:base_class)
+    (klass && (klass != rep.class)) ? rep.becomes(klass) : rep
+  end
+
+  def count
+    items.length
+  end
+end

data/lib/hal_api/rails.rb

@@ -0,0 +1,15 @@
+require "hal_api/rails/version"
+require "hal_api"
+
+module HalApi::Rails
+  require "responders"
+
+  Mime::Type.register 'application/hal+json', :hal
+
+  # roar fix for 4.1
+  # https://github.com/apotonick/roar-rails/issues/65
+  ::ActionController::Renderers.add :hal do |js, options|
+    self.content_type ||= Mime::HAL
+    js.to_json
+  end
+end

data/lib/hal_api/rails/version.rb

@@ -0,0 +1,5 @@
+module HalApi
+  module Rails
+    VERSION = "0.2.0"
+  end
+end

data/lib/hal_api/represented_model.rb

@@ -0,0 +1,21 @@
+# encoding: utf-8
+
+module HalApi::RepresentedModel
+  extend ActiveSupport::Concern
+
+  # this concept is used in result set, perhaps doesn't belong in model itself
+  # consider if there is a better way to do this - decorate model instead?
+  attr_accessor :is_root_resource
+
+  def is_root_resource
+    !!@is_root_resource
+  end
+
+  def show_curies
+    is_root_resource
+  end
+
+  included do
+    extend ActiveModel::Naming unless (method(:model_name) rescue nil)
+  end
+end

data/lib/hal_api/representer.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+class HalApi::Representer < Roar::Decorator
+  require 'hal_api/representer/caches'
+  require 'hal_api/representer/curies'
+  require 'hal_api/representer/embeds'
+  require 'hal_api/representer/format_keys'
+  require 'hal_api/representer/link_serialize'
+  require 'hal_api/representer/uri_methods'
+
+  include Roar::JSON::HAL
+  include HalApi::Representer::FormatKeys
+  include HalApi::Representer::UriMethods
+  include HalApi::Representer::Curies
+  include HalApi::Representer::Embeds
+  include HalApi::Representer::Caches
+  include HalApi::Representer::LinkSerialize
+  self_link
+  profile_link
+end

data/lib/hal_api/representer/caches.rb

@@ -0,0 +1,44 @@
+require 'active_support/concern'
+
+# expects underlying model to have filename, class, and id attributes
+module HalApi::Representer::Caches
+  extend ActiveSupport::Concern
+  require 'hal_api/representer/caches/serialized_json'
+
+  # Pass in an option for the format this is going `to_`
+  # used in caching the final string format of the obj
+  # rather than the intermediary `Hash`, a modest accelerant
+  def to_json(options={})
+    options[:to_] = :json
+    super(options)
+  end
+
+  # def create_representation_with(doc, options, format)
+  #   cache.fetch(cache_key(represented, options), cache_options) do
+  #     response = super(doc, options, format)
+  #     response = HalApi::Representer::Caches::SerializedJson.new(JSON.dump(response)) if (options[:to_] == :json)
+  #     response
+  #   end
+  # end
+
+  def cache_key(obj, options)
+    key_components = [cache_key_class_name]
+    key_components << (obj.try(:is_root_resource) ? 'r' : 'l')
+    key_components << obj
+    key_components << options.select{|k,v| Array(options['_keys']).include?(k.to_s)}
+
+    ActiveSupport::Cache.expand_cache_key(key_components)
+  end
+
+  def cache
+    Rails.cache
+  end
+
+  def cache_key_class_name
+    self.class.name.underscore.gsub(/_representer$/, "")
+  end
+
+  def cache_options
+    {compress: true, race_condition_ttl: 10, expires_in: 1.hour}
+  end
+end

data/lib/hal_api/representer/caches/serialized_json.rb

@@ -0,0 +1,9 @@
+# Wrapper for string that is already json
+# inspired by: http://grosser.it/2013/10/16/compiled-json-for-partially-cached-json-response-precompiled-handlebar-templates/
+class HalApi::Representer::Caches::SerializedJson
+  def initialize(s); @s = s; end
+  def to_json(*args); @s; end
+  def to_s; @s; end
+
+  undef_method :as_json
+end

data/lib/hal_api/representer/curies.rb

@@ -0,0 +1,62 @@
+require 'active_support/concern'
+
+module HalApi::Representer::Curies
+  extend ActiveSupport::Concern
+
+  included do
+    class_eval do
+      class_attribute :default_curie, instance_writer: false
+    end
+  end
+
+  module ClassMethods
+
+    LINK_RELATIONS = %w(about alternate appendix archives author bookmark
+    canonical chapter collection contents copyright create-form curies current
+    describedby describes disclosure duplicate edit edit-form edit-media
+    enclosure first glossary help hosts hub icon index item last latest-version
+    license lrdd memento monitor monitor-group next next-archive nofollow
+    noreferrer original payment predecessor-version prefetch prev preview
+    previous prev-archive privacy-policy profile related replies search section
+    self service start stylesheet subsection successor-version tag
+    terms-of-service timegate timemap type up version-history via working-copy
+    working-copy-of)
+
+    def use_curie(curie)
+      self.default_curie = curie
+    end
+
+    def curies(curie, &block)
+      use_curie(curie) unless default_curie
+      link({rel: :curies, array: true}) do
+        if represented.try(:show_curies)
+          block.call
+        end
+      end
+    end
+
+    def curify(rel, curie=default_curie)
+      if curie.blank? || rel.to_s =~ /:/ || LINK_RELATIONS.include?(rel.to_s)
+        rel
+      else
+        "#{curie}:#{rel}".to_sym
+      end
+    end
+
+    def link(options, &block)
+      options = {:rel => options} unless options.is_a?(Hash)
+      options[:rel] = curify(options[:rel])
+      super(options, &block)
+    end
+
+    def property(name, options={})
+      options[:as] = curify(options[:as] || name) if options[:embedded]
+      super(name, options)
+    end
+
+    def collection(name, options={})
+      options[:as] = curify(options[:as] || name) if options[:embedded]
+      super(name, options)
+    end
+  end
+end

data/lib/hal_api/representer/embeds.rb

@@ -0,0 +1,87 @@
+require 'active_support/concern'
+
+# expects underlying model to have filename, class, and id attributes
+module HalApi::Representer::Embeds
+  extend ActiveSupport::Concern
+
+  included do
+    Representable::Mapper.send(:include, Resources) if !Representable::Mapper.include?(Resources)
+  end
+
+  module Resources
+
+    def skip_property?(binding, options)
+      super(binding, options) || suppress_embed?(binding, options)
+    end
+
+    # embed if zoomed
+    def suppress_embed?(binding, options)
+      name     = (binding[:as] || binding.name).to_s
+      embedded = !!binding[:embedded]
+
+      # not embedded, return false - nothing to suppress
+      return false if !embedded
+
+      # check if it should be zoomed, suppress if not
+      !embed_zoomed?(name, binding[:zoom], options[:zoom])
+    end
+
+    def embed_zoomed?(name, zoom_def=nil, zoom_param=nil)
+      # if the embed in the representer definition has `zoom: :always` defined
+      # always embed it, even if it is in another embed
+      # (this is really meant for collections where embedded items must be included)
+      return true if zoom_def == :always
+
+      # passing nil explicitly overwrites defaults in signature,
+      # so we default to nil and fix in the method body
+      zoom_def = true if zoom_def.nil?
+
+      # if there is no zoom specified in the request params (options)
+      # then embed based on the zoom option in the representer definition
+
+      # if there is a zoom specified in the request params (options)
+      # then do not zoom when this name is not in the request
+      zoom_param.nil? ? zoom_def : zoom_param.include?(name)
+    end
+  end
+
+  # Possible values for zoom option in the embed representer definition
+  # * false - will be zoomed only if in the root doc and in the zoom param
+  # * true - zoomed in root doc if no zoom_param, or if included in zoom_param
+  # * always - zoomed no matter what is in zoom param, and even if in embed
+  module ClassMethods
+
+    def embed(name, options={})
+      options[:embedded] = true
+      options[:writeable] = false
+      options[:if] ||= ->(_a) { id } unless options[:zoom] == :always
+
+      if options[:paged]
+        opts = {
+          no_curies: true,
+          item_class: options.delete(:item_class),
+          url: options.delete(:url),
+          item_decorator: options.delete(:item_decorator),
+          per: options.delete(:per) || Kaminari.config.default_per_page
+        }
+        options[:getter] ||= ->(*) do
+          # set # per page based on default, option value integer, or special :all
+          per = opts.delete(:per)
+          per = self.send(name).count if per == :all
+          PagedCollection.new(self.send(name).page(1).per(per), nil, opts.merge({parent: self}))
+        end
+        options[:decorator] = Api::PagedCollectionRepresenter
+      end
+
+      property(name, options)
+    end
+
+    def embeds(name, options={})
+      options[:embedded] = true
+      options[:writeable] = false
+      options[:if] ||= ->(_a) { id } unless options[:zoom] == :always
+
+      collection(name, options)
+    end
+  end
+end

data/lib/hal_api/representer/format_keys.rb

@@ -0,0 +1,28 @@
+require 'active_support/concern'
+
+# Link relation names seem to have a standard of being dasherized, as they are URIs
+# property names, on the other hand should, should be camelcase, lower first
+module HalApi::Representer::FormatKeys
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+
+    def link(options, &block)
+      options = {:rel => options} unless options.is_a?(Hash)
+      options[:rel] = options[:rel].to_s.dasherize
+      super(options, &block)
+    end
+
+    def property(name, options={})
+      n = (options[:as] || name).to_s
+      options[:as] = options[:embedded] ? n.dasherize : n.camelize(:lower)
+      super(name, options)
+    end
+
+    def collection(name, options={})
+      n = (options[:as] || name).to_s
+      options[:as] = options[:embedded] ? n.dasherize : n.camelize(:lower)
+      super(name, options)
+    end
+  end
+end

data/lib/hal_api/representer/link_serialize.rb

@@ -0,0 +1,26 @@
+require 'active_support/concern'
+
+module HalApi::Representer::LinkSerialize
+
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+
+    def link(options, &block)
+      set_link_property(options)
+      super(options, &block)
+    end
+
+    def set_link_property(options)
+      if options.is_a?(Hash) && (options.delete(:writeable) || options[:reader])
+        name   = options[:rel].to_s.split(':').last.split('/').last
+        pname  = "set_#{name}_uri"
+        reader = options.delete(:reader) || ->(doc, _args) do
+          try("#{name}_id=", id_from_url(doc[pname])) if doc[pname]
+        end
+
+        property(pname, readable: false, reader: reader)
+      end
+    end
+  end
+end