granola 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 889ae25405985efae9deccf2120d07a6c9e18562
-  data.tar.gz: faa849493f9d6e280d370a3e28852e153ac594f3
+  metadata.gz: 5e69b46c3904138a9b629c06935167c86d96e121
+  data.tar.gz: 869dc7ae697f696c5f65ede168e87b435320e472
 SHA512:
-  metadata.gz: f2f705f01edc749d319c9e5a0cdf6eb0689cea3575152e9ba1696138c48a979a4e86d8b5fc5a69079060166162af3bc6efa79219e0ca61f9ff73115bae9aee22
-  data.tar.gz: 3c711e64c563d5c68e18a7e4490c96ad2889ca2d3c9b2147c5c375bdafa04c72082454e5045551c73513398cb5bf6db7d5975eb482c808f0c2703d14bfc6242b
+  metadata.gz: 00b2b5b36f45cc56c884b9eaabc02aa8aef1b65cfb30480f54cf9568d3f12d992170b5961226c1b368ad60fd20e1ee30de68866a588149c1015954b74ccd884e
+  data.tar.gz: 3ad2e3746539fc912d747ed414d5aaca1498e4ff0fe35f35c3913ee75afe61edfe5659e65648999b4a62283b0ee1f7f1d004b37df8699a11f78370b7b786ccd4

data/README.md

@@ -51,8 +51,9 @@ serializer.to_json #=> '[{"name":"John Doe",...},{...}]'
 
 ## Rack Helpers
 
-If your application is based on Rack, you can simply `include Granola::Rack` and
-you get access to the following interface:
+If your application is based on Rack, you can `require "granola/rack"` instead
+of `require "granola"`, and then simply `include Granola::Rack` to get access
+to the following interface:
 
 ``` ruby
 granola(person) #=> This will infer PersonSerializer from a Person instance
@@ -63,6 +64,8 @@ This method returns a Rack response tuple that you can use like so (this example
 uses [Cuba][], but similar code will work for other frameworks):
 
 ``` ruby
+require "granola/rack"
+
 Cuba.plugin Granola::Rack
 
 Cuba.define do
@@ -142,6 +145,18 @@ granola(object, as: :msgpack)
 
 This will set the correct MIME type.
 
+If you don't explicitly set a format when rendering via the rack helper, Granola
+will use the request's `Accept` header to choose the best format for rendering.
+
+For example, given a request with the following header:
+
+    Accept: text/x-yaml;q=0.5,application/x-msgpack;q=0.8,*/*;q=0.2
+
+Granola will check first if you have a renderer registered for the
+`application/x-msgpack` MIME type, and then check for a renderer for the
+`text/x-yaml` MIME type. If none of these are registered, it will default to
+rendering JSON.
+
 [msgpack-ruby]: https://github.com/msgpack/msgpack-ruby
 
 ## License

data/lib/granola.rb

@@ -1,4 +1,5 @@
+# frozen_string_literal: true
 require "granola/version"
 require "granola/serializer"
 require "granola/rendering"
-require "granola/rack"
+require "granola/util"

data/lib/granola/rack.rb

@@ -1,8 +1,8 @@
+# frozen_string_literal: true
 require "digest/md5"
 require "time"
-require "granola/serializer"
-require "granola/util"
-require "granola/caching"
+require "granola"
+require "rack/utils"
 
 module Granola
   # Mixin to render JSON in the context of a Rack application. See the #json
@@ -29,6 +29,8 @@ module Granola
     #            example, MsgPack.
     #   status:  The HTTP status to return on stale responses. Defaults to `200`
     #   headers: A Hash of default HTTP headers. Defaults to an empty Hash.
+    #   env:     Rack's env-Hash to inspect request headers. Defaults to
+    #            an `env` method in the object that includes `Granola::Rack`.
     #   **opts:  Any other keywords passed will be forwarded to the serializer's
     #            serialization backend call.
     #
@@ -36,24 +38,52 @@ module Granola
     # infer one for this object.
     #
     # Returns a Rack response tuple.
-    def granola(object, with: nil, status: 200, headers: {}, as: :json, **opts)
+    def granola(object, with: nil, status: 200, headers: {}, as: nil, env: self.env, **opts)
       serializer = Granola::Util.serializer_for(object, with: with)
 
       if serializer.last_modified
-        headers["Last-Modified".freeze] = serializer.last_modified.httpdate
+        headers["Last-Modified"] = serializer.last_modified.httpdate
       end
 
       if serializer.cache_key
-        headers["ETag".freeze] = Digest::MD5.hexdigest(serializer.cache_key)
+        headers["ETag"] = Digest::MD5.hexdigest(serializer.cache_key)
       end
 
-      headers["Content-Type".freeze] = serializer.mime_type(as)
+      renderer = Granola.renderer(
+        as || Granola::Rack.best_format_for(env["HTTP_ACCEPT"]) || :json
+      )
+
+      headers["Content-Type"] = renderer.content_type
 
       body = Enumerator.new do |yielder|
-        yielder << serializer.render(as, opts)
+        yielder << renderer.render(serializer, opts)
       end
 
       [status, headers, body]
     end
+
+    # Internal: Infer the best rendering format based on the value of an Accept
+    # header and the available registered renderers.
+    #
+    # If there are renderers registered for JSON, and MessagePack, an Accept
+    # header preferring MessagePack over JSON will result in the response being
+    # serialized into MessagePack instead of JSON, unless the user explicitly
+    # prefers JSON.
+    #
+    # accept  - String with the value of an HTTP Accept header.
+    # formats - Map of registered renderers. Defaults to
+    #           `Granola.renderable_formats`.
+    #
+    # Returns a Symbol with a Renderer type, or `nil` if none could be inferred.
+    def self.best_format_for(accept, formats = Granola.renderable_formats)
+      formats = formats.map { |f| [Granola.renderer(f).content_type, f] }.to_h
+
+      ::Rack::Utils.q_values(accept).sort_by { |_, q| -q }.each do |type, _|
+        format = formats[type]
+        return format unless format.nil?
+      end
+
+      nil
+    end
   end
 end

data/lib/granola/rendering.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+require "json"
+
+module Granola
+  class NoSuchRendererError < ArgumentError; end
+
+  # Public: Register a new Renderer. A Renderer must be a callable that, given
+  # the output of a Serializer's `data` method, will turn that into a stream
+  # of the expected type.
+  #
+  # Registering a Renderer via this method will add a `to_#{type}` instance
+  # method to the serializers, as syntax sugar for calling `Renderer#render`.
+  #
+  # type          - A name to identify this rendering mechanism. For example,
+  #                 `:json`.
+  # via:          - A callable that performs the actual rendering. See
+  #                 Renderer#initialize for a description of the interface
+  #                 expected of this callable.
+  # content_type: - String with the expected content type when rendering
+  #                 serializers in a web context. For example,
+  #                 `"application/json"`
+  #
+  # Example:
+  #
+  #   Granola::Serializer.render(:json, {
+  #     via: Oj.method(:dump),
+  #     content_type: "application/json"
+  #   })
+  #
+  #   Granola::Serializer.render(:msgpack, {
+  #     via: MessagePack.method(:pack),
+  #     content_type: "application/x-msgpack"
+  #   })
+  #
+  # Returns nothing.
+  def self.render(type, via:, content_type:)
+    RENDERERS[type.to_sym] = Renderer.new(via, content_type)
+    Serializer.send :define_method, "to_#{type}" do |**opts, &block|
+      Granola.renderer(type).render(self, **opts, &block)
+    end
+  end
+
+  # Public: Get a registered Renderer.
+  #
+  # type - A Symbol with the name under which a Renderer was registered. See
+  #        `Granola.render`.
+  #
+  # Raises Granola::NoSuchRendererError if an unknown `type` is passed.
+  # Returns a Granola::Renderer instance.
+  def self.renderer(type)
+    RENDERERS.fetch(type.to_sym) do
+      fail NoSuchRendererError, "No renderer registered for #{type.inspect}"
+    end
+  end
+
+  # Public: Returns an Array of types with a registered Renderer as Symbols. See
+  # `Granola.render` to register a new Renderer instance.
+  def self.renderable_formats
+    RENDERERS.keys
+  end
+
+  # Internal: Map of renderers available to this serializer.
+  RENDERERS = {}
+
+  # Renderer objects just wrap the callable used to render an object and keep a
+  # reference to the Content-Type that should be used when rendering objects
+  # through it.
+  #
+  # You shouldn't initialize this objects. Instead, use `Granola.render` to
+  # register rendering formats.
+  #
+  # Example:
+  #
+  #   Granola.render(:json, via: JSON.method(:generate),
+  #                         content_type: "application/json")
+  #
+  #   renderer = Granola.renderer(:json)
+  #   renderer.content_type #=> "application/json"
+  #   renderer.render(PersonSerializer.new(person)) #=> "{...}"
+  class Renderer
+    # Public: Get a String with the Renderer's expected content type.
+    attr_reader :content_type
+
+    # Internal: Initialize a renderer. You should't use this method. Instead,
+    # see `Granola.render` for registering a new rendering format.
+    #
+    # backend      - A callable that takes an object (the result of calling a
+    #                Serializer's `data` method) and returns a String of data
+    #                appropriately encoded for this rendering format.
+    # content_type - A String with the expected content type to be returned when
+    #                serializing objects through this renderer.
+    def initialize(backend, content_type)
+      @backend = backend
+      @content_type = content_type
+    end
+
+    # Public: Render a Serializer in this format.
+    #
+    # serializer - An instance of Granola::Serializer.
+    # options    - Any options that can be passed to the rendering backend.
+    #
+    # Returns a String.
+    def render(serializer, **options, &block)
+      @backend.call(serializer.data, **options, &block)
+    end
+  end
+
+  render :json, via: JSON.method(:generate), content_type: "application/json"
+
+  # Deprecated: The old way of registering a JSON renderer. This will be gone in
+  # 1.0.
+  #
+  # callable - A callable. See the format in `Granola.render`
+  #
+  # Returns nothing.
+  def self.json=(callable)
+    warn "Granola.json= has been deprecated. Use Granola.render now."
+    render(:json, via: callable, content_type: "application/json")
+  end
+
+  class Serializer
+    # Deprecated: Use Granola.renderer and a Renderer's render method directly.
+    # This method will be removed in 1.0.
+    #
+    # type      - A Symbol with the expected rendering format.
+    # **options - An options Hash or set of keyword arguments that will be
+    #             passed to the renderer.
+    #
+    # Raises KeyError if there's no Renderer registered for the given `type`.
+    # Returns a String (in the encoding approrpriate to the rendering format.)
+    def render(type = :json, **options, &block)
+      warn "Granola::Serializer#render has been deprecated. Use Granola.renderer(type).render."
+      Granola.renderer(type).render(self, **options, &block)
+    rescue NoSuchRendererError => err
+      fail KeyError, err.message
+    end
+
+    # Deprecated: Use Granola.renderer and the Renderer's content_type method
+    # directly. This method will be removed in 1.0.
+    #
+    # type - A Symbol describing the expected rendering format.
+    #
+    # Raises KeyError if there's no Renderer registered for the given `type`.
+    # Returns a String.
+    def mime_type(type = :json)
+      warn "Granola::Serializer#mime_type has been deprecated. Use Granola.renderer(type).content_type."
+      Granola.renderer(type).content_type
+    rescue NoSuchRendererError => err
+      fail KeyError, err.message
+    end
+  end
+end

data/lib/granola/serializer.rb

@@ -2,6 +2,7 @@ module Granola
   # A Serializer describes how to serialize a certain type of object, by
   # declaring the structure of JSON objects.
   class Serializer
+    # Public: Get the domain model to serialize.
     attr_reader :object
 
     # Public: Instantiates a list serializer that wraps around an iterable of
@@ -19,7 +20,7 @@ module Granola
 
     # Public: Initialize the serializer with a given object.
     #
-    # object - The domain model that we want to serialize into JSON.
+    # object - The domain model that we want to serialize.
     def initialize(object)
       @object = object
     end
@@ -33,6 +34,22 @@ module Granola
     def data
       fail NotImplementedError
     end
+
+    # Public: Provides a key that's unique to the current representation of the
+    # JSON object generated by the serializer. This will be MD5'd to become the
+    # ETag header that will be sent in responses.
+    #
+    # Returns a String or `nil`, indicaing that no ETag should be sent.
+    def cache_key
+    end
+
+    # Public: Provides the date of last modification of this entity. This will
+    # become the Last-Modified header that will be sent in responses, if
+    # present.
+    #
+    # Returns a Time or `nil`, indicating that no Last-Modified should be sent.
+    def last_modified
+    end
   end
 
   # Internal: The List serializer provides an interface for serializing lists of
@@ -66,5 +83,21 @@ module Granola
     def data
       @list.map(&:data)
     end
+
+    # Public: Defines a compound cache key by joining the cache key of any
+    # items of the collection, if they have one. See `Serializer#cache_key`.
+    #
+    # Returns a String or `nil`.
+    def cache_key
+      all = @list.map(&:cache_key).compact
+      all.join("-") if all.any?
+    end
+
+    # Public: Returns the newest modification Time out of the items in the
+    # collection, or `nil` if none have a `last_modified` set. See
+    # `Serializer#last_modified`.
+    def last_modified
+      @list.map(&:last_modified).compact.max
+    end
   end
 end

data/lib/granola/util.rb

@@ -1,7 +1,24 @@
+# frozen_string_literal: true
 require "granola/serializer"
 
 module Granola
   module Util
+    class << self
+      # Public: Get/Set the mechanism used to look up constants by name. This
+      # should be a callable that takes a String with a constant's name and
+      # converts this to a Serializer class, or fails with NameError.
+      #
+      # Example:
+      #
+      #   # Find serializers under Serializers::Foo instead of FooSerializer.
+      #   Granola::Util.constant_lookup = ->(name) do
+      #     Serializers.const_get(name.sub(/Serializer$/, ""))
+      #   end
+      attr_accessor :constant_lookup
+    end
+
+    self.constant_lookup = Object.method(:const_get)
+
     # Public: Returns the serializer object for rendering a specific object. The
     # class will attempt to be inferred based on the class of the passed object,
     # but a specific serializer can be passed via a keyword argument `with`.
@@ -36,11 +53,11 @@ module Granola
       object = object.respond_to?(:to_ary) ? object.to_ary[0] : object
 
       case object
-      when NilClass, TrueClass, FalseClass, Numeric, String
+      when Hash, NilClass, TrueClass, FalseClass, Numeric, String
         PrimitiveTypesSerializer
       else
         name = object.class.name
-        Object.const_get("%sSerializer" % name)
+        constant_lookup.call("%sSerializer" % name)
       end
     end
 

data/lib/granola/version.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Granola
-  VERSION = "0.11.0"
+  VERSION = "0.13.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: granola
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Nicolas Sanguinetti
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-11-12 00:00:00.000000000 Z
+date: 2016-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cutest
@@ -48,8 +48,8 @@ files:
 - LICENSE
 - README.md
 - lib/granola.rb
-- lib/granola/caching.rb
 - lib/granola/rack.rb
+- lib/granola/rendering.rb
 - lib/granola/serializer.rb
 - lib/granola/util.rb
 - lib/granola/version.rb

data/lib/granola/caching.rb

@@ -1,37 +0,0 @@
-require "granola/serializer"
-
-module Granola
-  # Mixin to add caching-awareness to Serializers.
-  module Caching
-    # Public: Provides a key that's unique to the current representation of the
-    # JSON object generated by the serializer. This will be MD5'd to become the
-    # ETag header that will be sent in responses.
-    #
-    # Returns a String or `nil`, indicaing that no ETag should be sent.
-    def cache_key
-    end
-
-    # Public: Provides the date of last modification of this entity. This will
-    # become the Last-Modified header that will be sent in responses, if
-    # present.
-    #
-    # Returns a Time or `nil`, indicating that no Last-Modified should be sent.
-    def last_modified
-    end
-  end
-
-  class Serializer
-    include Caching
-  end
-
-  class List < Serializer
-    def cache_key
-      all = @list.map(&:cache_key).compact
-      all.join("-") if all.any?
-    end
-
-    def last_modified
-      @list.map(&:last_modified).compact.sort.last
-    end
-  end
-end