granola 0.0.4 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c8736dc4a00f68a43630c02a5fd3f3aa21c46269
-  data.tar.gz: 2aabc2032b24dfe14a2ef9f08bcf088d0bb8f129
+  metadata.gz: bf1c567fa58a115fc7f8d55fa10ca0e0d482baa9
+  data.tar.gz: a6c5f64bf66e7445fc3f11c48ff046d66fd701c6
 SHA512:
-  metadata.gz: 688ceebc2a8cdcf7931d00359d3a31829d3fc0a05db7ffbf556ff99d195f4ffdc2f96b5c942be9a7f9ecc0d7b8a8702f9aa632c91d8b7fc636a446c01a134481
-  data.tar.gz: 633293c6115d1d81558932f7f04bdbf33b8a2b880e0e9fdef5b95f7e5edc20ac44b1a84951192e4652f249bc7c65cee29f29d04c48a63c12efc213fc11434edc
+  metadata.gz: a6918a2d025d20e08ea0f2756adafaa5d0dbf5134a2ad05059edfff3eba26e31d36ffbd7d0ae72a394243edad1d125317b09b40e4eb02aeba0fd31a2eb3e3e55
+  data.tar.gz: 2117365b5ee8f946ab307a6d2020d8beb0173d06adb26fd3e974272cfa95a8911f348ca5e78023f9c0b1755c6e21fceb332f45d76bb87a947050eae907e63284

data/README.md

@@ -1,4 +1,4 @@
-# Granola, a JSON serializer
+# Granola, a JSON serializer [![Build Status](https://travis-ci.org/foca/granola.svg?branch=master)](https://travis-ci.org/foca/granola)
 
 ![A tasty bowl of Granola](https://cloud.githubusercontent.com/assets/437/4827156/9e8d33da-5f76-11e4-8574-7803e84845f2.JPG)
 
@@ -11,7 +11,7 @@ gets out of your way. You just write plain ruby.
 
 ``` ruby
 class PersonSerializer < Granola::Serializer
-  def attributes
+  def serialized
     {
       "name" => object.name,
       "email" => object.email,
@@ -34,10 +34,14 @@ specific JSON backend. It defaults to the native JSON backend, but you're free
 to change it. For example, if you were using [Yajl][]:
 
 ``` ruby
-Granola.json = ->(obj, **opts) { Yajl::Encoder.encode(obj, opts) }
+Granola.json = Yajl::Encoder.method(:encode)
 ```
 
+If your project already uses [MultiJson][] then we will default to whatever it's
+using, so you shouldn't worry.
+
 [Yajl]: https://github.com/brianmario/yajl-ruby
+[MultiJson]: https://github.com/intridea/multi_json
 
 ## Handling lists of models
 
@@ -55,8 +59,8 @@ If your application is based on Rack, you can simply `include Granola::Rack` and
 you get access to the following interface:
 
 ``` ruby
-json(person) #=> This will try to infer PersonSerializer from a Person instance
-json(person, with: AnotherSerializer)
+granola(person) #=> This will infer PersonSerializer from a Person instance
+granola(person, with: AnotherSerializer)
 ```
 
 *NOTE* The method relies on being an `env` method that returns the Rack
@@ -72,7 +76,7 @@ Cuba.plugin Granola::Rack
 Cuba.define do
   on get, "users/:id" do |id|
     user = User[id]
-    halt json(user)
+    halt granola(user)
   end
 end
 ```
@@ -81,16 +85,77 @@ end
 
 ## Caching
 
-`Granola::Serializer` gives you to methods that you can implement in your
-serializers, `last_modified` and `cache_key`, that will be used to prevent
-rendering JSON at all if possible, when using the `Granola::Rack#json` helper.
+`Granola::Serializer` gives you two methods that you can implement in your
+serializers: `last_modified` and `cache_key`.
+
+When using the `Granola::Rack` module, you should return a `Time` object from
+your serializer's `last_modified`.  Granola will use this to generate the
+appropriate `Last-Modified` HTTP header.  Likewise, the result of `cache_key`
+will be MD5d and set as the response's `ETag` header.
+
+If you do this, you should also make sure that the [`Rack::ConditionalGet`][cg]
+middleware is in your Rack stack, as it will use these headers to avoid
+generating the JSON response altogether. For example, using Cuba:
+
+``` ruby
+class UserSerializer < Granola::Serializer
+  def serialized
+    { "id" => object.id, "name" => object.name, "email" => object.email }
+  end
+
+  def last_modified
+    object.updated_at
+  end
+
+  def cache_key
+    "user:#{object.id}:#{object.updated_at.to_i}"
+  end
+end
+
+Cuba.plugin Granola::Rack
+Cuba.use Rack::ConditionalGet
+
+Cuba.define do
+  on get, "users/:id" do |id|
+    halt granola(User[id])
+  end
+end
+```
+
+This will avoid generating the JSON response altogether if the user sends the
+appropriate `If-Modified-Since` or `If-None-Match` headers.
+
+[cg]: http://www.rubydoc.info/github/rack/rack/Rack/ConditionalGet
+
+## Different Formats
+
+Although Granola out of the box only ships with JSON serialization support, it's
+easy to extend and add support for different types of serialization in case your
+API needs to provide multiple formats. For example, in order to add MsgPack
+support (via the [msgpack-ruby][] library), you'd do this:
+
+``` ruby
+require "msgpack"
+
+class BaseSerializer < Granola::Serializer
+  MIME_TYPES[:msgpack] = "application/x-msgpack".freeze
+
+  def to_msgpack(*)
+    MsgPack.pack(serialized)
+  end
+end
+```
+
+Now all serializers that inherit from `BaseSerializer` can be serialized into
+MsgPack. In order to use this from our Rack helpers, you'd do:
+
+``` ruby
+granola(object, as: :msgpack)
+```
 
-If your serializer implements this method, and the `env` has the appropriate
-`If-Modified-Since` or `If-None-Match` headers, the helper will automatically
-return a 304 response.
+This will set the correct MIME type.
 
-Plus, it sets appropriate `ETag` and `Last-Modified` so your clients can avoid
-hitting the endpoint altogether.
+[msgpack-ruby]: https://github.com/msgpack/msgpack-ruby
 
 ## License
 

data/lib/granola.rb

@@ -16,13 +16,21 @@ module Granola
     attr_accessor :json
   end
 
-  self.json = ->(obj, **opts) { JSON.dump(obj) }
+  if defined?(MultiJson)
+    self.json = MultiJson.method(:dump)
+  else
+    self.json = JSON.method(:generate)
+  end
 
   # A Serializer describes how to serialize a certain type of object, by
   # declaring the structure of JSON objects.
   class Serializer
     attr_reader :object
 
+    # Public: Map of the default MIME type for each given type of serialization
+    # for this object.
+    MIME_TYPES = { json: "application/json".freeze }
+
     # Public: Instantiates a list serializer that wraps around an iterable of
     # objects of the type expected by this serializer class.
     #
@@ -32,8 +40,8 @@ module Granola
     #   serializer.to_json
     #
     # Returns a Granola::List.
-    def self.list(ary)
-      List.new(ary, self)
+    def self.list(ary, *args)
+      List.new(ary, *args, with: self)
     end
 
     # Public: Initialize the serializer with a given object.
@@ -43,11 +51,13 @@ module Granola
       @object = object
     end
 
-    # Public: Returns the Hash of attributes that should be serialized into
-    # JSON.
+    # Public: Returns a primitive Object that can be serialized into JSON,
+    # meaning one of `nil`, `true`, `false`, a String, a Numeric, an Array of
+    # primitive objects, or a Hash with String keys and primitive objects as
+    # values.
     #
     # Raises NotImplementedError unless you override in subclasses.
-    def attributes
+    def serialized
       fail NotImplementedError
     end
 
@@ -57,25 +67,28 @@ module Granola
     #
     # Returns a String.
     def to_json(**options)
-      Granola.json.(attributes, options)
+      Granola.json.(serialized, options)
     end
 
     # Public: Returns the MIME type generated by this serializer. By default
     # this will be `application/json`, but you can override in your serializers
     # if your API uses a different MIME type (e.g. `application/my-app+json`).
     #
+    # type - A Symbol describing the expected mime type.
+    #
     # Returns a String.
-    def mime_type
-      "application/json".freeze
+    def mime_type(type = :json)
+      MIME_TYPES.fetch(type)
     end
   end
 
   # Internal: The List serializer provides an interface for serializing lists of
-  # objects, wrapping around a specific serializer.
+  # objects, wrapping around a specific serializer. The preferred API for this
+  # is to use `Granola::Serializer.list`.
   #
   # Example:
   #
-  #   serializer = Granola::List.new(people, PersonSerializer)
+  #   serializer = Granola::List.new(people, with: PersonSerializer)
   #   serializer.to_json
   #
   # You should use Serializer.list instead of this class.
@@ -85,16 +98,20 @@ module Granola
 
     # Public: Instantiate a new list serializer.
     #
-    # list       - An Array-like structure.
-    # serializer - A subclass of Granola::Serializer.
-    def initialize(list, serializer)
-      @item_serializer = serializer
-      @list = list.map { |obj| serializer.new(obj) }
+    # list  - An Array-like structure.
+    # *args - Any other arguments that the item serializer takes.
+    #
+    # Keywords:
+    #   with: The subclass of Granola::Serializer to use when serializing
+    #         specific elements in the list.
+    def initialize(list, *args, with: serializer)
+      @item_serializer = with
+      @list = list.map { |obj| @item_serializer.new(obj, *args) }
     end
 
     # Public: Returns an Array of Hashes that can be serialized into JSON.
-    def attributes
-      @list.map(&:attributes)
+    def serialized
+      @list.map(&:serialized)
     end
   end
 end

data/lib/granola/helper.rb

@@ -35,14 +35,19 @@ module Granola::Helper
     name = object.class.name
     Object.const_get("%sSerializer" % name)
   rescue NameError
-    const_get("%sSerializer" % name)
+    case object
+    when NilClass, TrueClass, FalseClass, Numeric, String
+      PrimitiveTypesSerializer
+    else
+      raise
+    end
   end
 
   # Internal: Null serializer that transparently handles rendering `nil` in case
   # it's passed.
-  class NilClassSerializer < Granola::Serializer
-    def attributes
-      {}
+  class PrimitiveTypesSerializer < Granola::Serializer
+    def serialized
+      object
     end
   end
 end

data/lib/granola/rack.rb

@@ -13,29 +13,33 @@ module Granola::Rack
 
   # Public: Renders a JSON representation of an object using a
   # Granola::Serializer. This takes care of setting the `Last-Modified` and
-  # `ETag` headers if appropriate, and of controlling whether the object should
-  # be rendered at all or not (issuing a 304 response in this case).
+  # `ETag` headers if appropriate.
   #
-  # This expects the class mixing in this module to implement an `env` method,
-  # that should be a Rack environment Hash.
+  # You can customize the response tuple by passing the status and the default
+  # headers, as in the following example:
+  #
+  #   granola(user, status: 400, headers: { "X-Error" => "Boom!" })
   #
   # object - An object to serialize into JSON.
   #
   # Keywords:
-  #   with:           A specific serializer class to use. If this is `nil`,
-  #                   `Helper.serializer_class_for` will be used to infer the
-  #                   serializer class.
-  #   status:         The HTTP status to return on stale responses. Defaults to
-  #                   `200`.
-  #   **json_options: Any other keywords passed will be forwarded to the
-  #                   serializer's `#to_json` call.
+  #   with:    A specific serializer class to use. If this is `nil`,
+  #            `Helper.serializer_class_for` will be used to infer the
+  #            serializer class.
+  #   as:      A Symbol with the type of serialization desired. Defaults to
+  #            `:json` (and it's the only one available with Granola by default)
+  #            but could be expanded with plugins to provide serialization to,
+  #            for 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.
+  #   **opts:  Any other keywords passed will be forwarded to the serializer's
+  #            serialization backend call.
   #
   # Raises NameError if no specific serializer is provided and we fail to infer
   #   one for this object.
   # Returns a Rack response tuple.
-  def json(object, with: nil, status: 200, **json_options)
+  def granola(object, with: nil, status: 200, headers: {}, as: :json, **opts)
     serializer = serializer_for(object, with: with)
-    headers = {}
 
     if serializer.last_modified
       headers["Last-Modified".freeze] = serializer.last_modified.httpdate
@@ -45,87 +49,10 @@ module Granola::Rack
       headers["ETag".freeze] = Digest::MD5.hexdigest(serializer.cache_key)
     end
 
-    stale_check = StaleCheck.new(
-      env,
-      last_modified: headers["Last-Modified".freeze],
-      etag: headers["ETag".freeze]
-    )
-
-    if stale_check.fresh?
-      [304, headers, []]
-    else
-      json_string = serializer.to_json(json_options)
-      headers["Content-Type".freeze] = serializer.mime_type
-      headers["Content-Length".freeze] = json_string.length.to_s
-      [status, headers, [json_string]]
-    end
-  end
-
-  # Internal: Check whether a request is fresh or stale by both modified time
-  # and/or etag.
-  class StaleCheck
-    # Internal: Get the env Hash of the request.
-    attr_reader :env
-
-    # Internal: Get the Time at which the domain model was last-modified.
-    attr_reader :last_modified
-
-    # Internal: Get the String with the ETag ggenerated by this domain model.
-    attr_reader :etag
-
-    IF_MODIFIED_SINCE = "HTTP_IF_MODIFIED_SINCE".freeze
-    IF_NONE_MATCH = "HTTP_IF_NONE_MATCH".freeze
-
-    # Public: Initialize the check.
-    #
-    # env - Rack's env Hash.
-    #
-    # Keywords:
-    #   last_modified: The Time at which the domain model was last modified, if
-    #                  applicable (Defaults to `nil`).
-    #   etag:          The HTTP ETag for this domain model, if applicable
-    #                  (Defaults to `nil`).
-    def initialize(env, last_modified: nil, etag: nil)
-      @env = env
-      @last_modified = last_modified
-      @etag = etag
-    end
-
-    # Public: Checks whether the request is fresh. A fresh request is one that
-    # is stored in the client's cache and doesn't need updating (so it can be
-    # responded to with a 304 response).
-    #
-    # Returns Boolean.
-    def fresh?
-      fresh_by_time? || fresh_by_etag?
-    end
-
-    # Public: Returns a Boolean denoting whether the request is stale (i.e. not
-    # fresh).
-    def stale?
-      !fresh?
-    end
+    headers["Content-Type".freeze] = serializer.mime_type(as)
 
-    # Internal: Checks if a request is fresh by modified time, if applicable, by
-    # comparing the `If-Modified-Since` header with the last modified time of
-    # the domain model.
-    #
-    # Returns Boolean.
-    def fresh_by_time?
-      return false unless env.key?(IF_MODIFIED_SINCE) && !last_modified.nil?
-      Time.parse(last_modified) <= Time.parse(env.fetch(IF_MODIFIED_SINCE))
-    end
+    body = Enumerator.new { |y| y << serializer.public_send(:"to_#{as}", opts) }
 
-    # Internal: Checks if a request is fresh by etag, if applicable, by
-    # comparing the `If-None-Match` header with the ETag for the domain model.
-    #
-    # Returns Boolean.
-    def fresh_by_etag?
-      return false unless env.key?(IF_NONE_MATCH) && !etag.nil?
-      if_none_match = env.fetch(IF_NONE_MATCH, "").split(/\s*,\s*/)
-      return false if if_none_match.empty?
-      return true if if_none_match.include?("*".freeze)
-      if_none_match.any? { |tag| tag == etag }
-    end
+    [status, headers, body]
   end
 end

data/lib/granola/version.rb

@@ -1,3 +1,3 @@
 module Granola
-  VERSION = "0.0.4"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: granola
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.9.0
 platform: ruby
 authors:
 - Nicolas Sanguinetti
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-23 00:00:00.000000000 Z
+date: 2015-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cutest