jahuty 3.0.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f16f42cd41d86fdcdbd27591e637d82c324828f5cf60b3388afd7f1d439f9bee
-  data.tar.gz: 53ef3b027c56ac0a00a09ab8ba0a10a3794b0d47bab1975ceb64dfbce74a244c
+  metadata.gz: 93d706c72d12cb61d951cc71b8add1ac154ed8b8bc57374e3d558e2b4bd8d420
+  data.tar.gz: e64a1355073ba942c5aef652032e8268e4d3a065b8cb3f5a7594d590957edc18
 SHA512:
-  metadata.gz: 24affb2a47535cd18148a52a51ed5f67120032ff859f54995433c10f1348cc72db3d17017b58e3e90a473678c7639acecc14832fe6b6cea302342baa46bc8821
-  data.tar.gz: f4429c45c905b4dd9336d1126d4256dc9bdbf0f0c548f52bc7c93a8dc7371882bafdb11b29e18644816b1378a1d4691c7c7c6796c5a1c9a7cd68a6b90ab445a6
+  metadata.gz: 33d77db35616e1ae68f3b1ad0063e51ccfc526e35f2ef04e07851f506e5103e73af9d0d27252abf817de4ce2664206cf3edd7f9972275b96aaa582c8c38d0a7b
+  data.tar.gz: b572333f5df0d13b18ecbf29f9d22b06400622cdf9ab5408a6963f21fe154ea0fbb67cee881b3efb89cc7417ef1ef1abcd733b0681f7d72261f8ac357e175bc1

data/.rubocop.yml

@@ -4,9 +4,20 @@ require:
 AllCops:
   TargetRubyVersion: 2.6
   NewCops: enable
+  Exclude:
+   - vendor/bundle/**/*
 Metrics/BlockLength:
   Exclude:
     - 'jahuty.gemspec'
     - 'Rakefile'
     - '**/*.rake'
     - 'spec/**/*.rb'
+Metrics/ModuleLength:
+  Exclude:
+    - 'spec/**/*.rb'
+RSpec/ExampleLength:
+  Exclude:
+    - 'spec/jahuty/system_spec.rb'
+RSpec/MultipleExpectations:
+  Exclude:
+    - 'spec/jahuty/system_spec.rb'

data/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 3.3.0 - 2020-04-29
+
+- Add the `prefer_latest` configuration option to the client and render methods. This setting allows you to render a snippet's _latest_ content instead of the default _published_ content.
+
+## 3.2.1 - 2020-03-16
+
+* Fix issue with double-enveloping the `params` query string parameter.
+* Add system tests for params, caching, problems, and collections.
+
+## 3.2.0 - 2020-03-08
+
+* Added collections to the library with `all_renders` method. This was a rather large change and required adding new objects like `Action::Show`, refactoring old ones like `Resource::Factory`, and removing some objects like `Cache::Manager` and `Service::Factory` which added unnecessary complexity.
+* Added `snippet_id` to `Resource::Render` to help keep track of a render's parent snippet.
+
+## 3.1.1 - 2020-02-26
+
+- Add support for extra, unused attributes returned by the API to support evolution.
+- Fix the `method redefined` warnings in `cache/manager_spec.rb` and `cache/facade_spec.rb`.
+- Fix the `expect { }.not_to raise_error(SpecificErrorClass)` false positives warnings in `resource/render_spec.rb`.
+
+## 3.1.0 - 2020-01-04
+
+- Add caching support for any cache implementation that supports `get/set` or `read/write` methods.
+- Default to using in-memory [mini-cache](https://github.com/derrickreimer/mini_cache) storage.
+
 ## 3.0.0 - 2020-12-30
 
 - Change from a static-based architecture (e.g., `Jahuty::Snippet.render(1)`) to an instance-based one (e.g., `jahuty.snippets.render(1)`) to make the library easier to develop, test, and use.

data/README.md

@@ -10,28 +10,28 @@ This library requires [Ruby 2.6+](https://www.ruby-lang.org/en/downloads/release
 
 It is multi-platform, and we strive to make it run equally well on Windows, Linux, and OSX.
 
-Add this line to your application's `Gemfile`:
+To install, add this line to your application's `Gemfile` and run `bundle install`:
 
 ```ruby
-gem 'jahuty', '~> 3.0'
+gem 'jahuty', '~> 3.3'
 ```
 
 ## Usage
 
-Instantiate the client with your [API key](https://docs.jahuty.com/api#authentication) and use `snippets.render()` to render your snippet:
+Instantiate the client with your [API key](https://docs.jahuty.com/api#authentication) and use `snippets.render` to render your snippet:
 
 ```ruby
 jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
 
-puts jahuty.snippets.render(YOUR_SNIPPET_ID)
+puts jahuty.snippets.render YOUR_SNIPPET_ID
 ```
 
-You can also access the render's content with `to_s` or `content`:
+You can access the render's content with `to_s` or `content`:
 
 ```ruby
 jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
 
-render = jahuty.snippets.render(YOUR_SNIPPET_ID)
+render = jahuty.snippets.render YOUR_SNIPPET_ID
 
 a = render.to_s
 
@@ -43,42 +43,216 @@ a == b  # returns true
 In an HTML view:
 
 ```html+erb
-<%-
-  jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
-%>
+<%- jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY') -%>
 <!doctype html>
 <html>
 <head>
     <title>Awesome example</title>
 </head>
 <body>
-    <%= jahuty.snippets.render YOUR_SNIPPET_ID %>
+    <%== jahuty.snippets.render YOUR_SNIPPET_ID %>
 </body>
 ```
 
-## Parameters
+You can also use tags to render a collection of snippets with the `snippets.all_renders` method:
+
+```ruby
+jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
+
+renders = jahuty.snippets.all_renders 'YOUR_TAG'
+
+renders.each { |render| puts render }
+```
+
+## Rendering content
+
+You can use the `prefer_latest` configuration option to render a snippet's _latest_ content to your team in _development_ and its _published_ content to your customers in _production_.
 
-You can [pass parameters](https://docs.jahuty.com/liquid/parameters) into your snippet using the `params` option:
+By default, Jahuty will render a snippet's _published_ content, the content that existed the last time someone clicked the "Publish" button, to avoid exposing your creative process to customers.
+
+To render a snippet's _latest_ content, the content that currently exists in the editor, you can use the `prefer_latest` configuration option at the library or render level:
+
+```ruby
+jahuty = Jahuty::Client.new api_key: 'YOUR_API_KEY', prefer_latest: true
+```
+
+You can also prefer the latest content (or not) for a single render:
+
+```ruby
+# Render the _published_ content for all snippets...
+jahuty = Jahuty::Client.new api_key: 'YOUR_API_KEY'
+
+# ... except, render the _latest_ content for this one.
+jahuty.snippets.render YOUR_SNIPPET_ID, prefer_latest: true
+```
+
+## Passing dynamic parameters
+
+You can use the _same_ snippet to generate _different_ content by defining [variables](https://docs.jahuty.com/liquid/variables) in your snippets and setting their values via [parameters](https://docs.jahuty.com/liquid/parameters).
+
+### Snippet parameters
+
+Use the `params` option to pass parameters into your snippet:
 
 ```ruby
 jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
 
-jahuty.snippets.render(YOUR_SNIPPET_ID, params: { foo: 'bar' });
+jahuty.snippets.render YOUR_SNIPPET_ID, params: { foo: 'bar' }
 ```
 
-The parameters above would be equivalent to [assigning the variable](https://docs.jahuty.com/liquid/variables) below in your snippet:
+The parameters above would be equivalent to assigning the following variable in your snippet:
 
 ```html
 {% assign foo = "bar" %}
 ```
 
-## Errors
+### Collection parameters
 
-If an error occurs with [Jahuty's API](https://docs.jahuty.com/api#errors), a `Jahuty::Exception::Error` will be raised:
+Collection parameters use a slightly different syntax.
+
+If you're rendering a collection, the first dimension of the `params` key determines the parameters' scope. Use an asterisk key (`*`) to pass the same parameters to all snippets, or use a snippet id as key to pass parameters to a specific snippet.
+
+```ruby
+jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
+
+jahuty.snippets.all_renders 'YOUR_TAG', params: {
+  '*' => { foo: 'bar' },
+  '1' => { baz: 'qux' }
+}
+```
+
+This will pass the params `{ foo: 'bar' }` to all snippets, except for snippet `1`, which will be passed `{ foo: 'bar', baz: 'qux' }`.
+
+The two parameter lists will be merged recursively, and parameters for a specific snippet will take precedence over parameters for all snippets. For example, the parameter `foo` will be assigned the value `"bar"` for all snippets, except for snippet `1`, where it will be assigned the value `"qux"`:
 
 ```ruby
-require 'jahuty'
+jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
+
+jahuty.snippets.all_renders 'YOUR_TAG', params: {
+  '*' => { foo: 'bar' },
+  '1' => { foo: 'qux' }
+}
+```
+
+## Caching for performance
+
+You can use caching to control how frequently this library requests the latest content from Jahuty's API.
+
+* When content is in _development_ (i.e., frequently changing and low traffic), you can use the default in-memory store to view content changes instantaneously with slower response times.
+* When content is in _production_ (i.e., more stable and high traffic), you can use persistent caching to update content less frequently and improve your application's response time.
+
+### Caching in memory (default)
+
+By default, this library uses an in-memory cache to avoid requesting the same render more than once during the same request lifecycle. For example:
+
+```ruby
+jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
+
+# This call will send a synchronous API request; cache the result in memory;
+# and, return the result to the caller.
+render1 = jahuty.snippets.render YOUR_SNIPPET_ID
+
+# This call skips sending an API request and uses the cached value instead.
+render2 = jahuty.snippets.render YOUR_SNIPPET_ID
+```
+
+The in-memory cache only persists for the duration of the original request, however. At the end of the request's lifecycle, the cache will be discarded. To store renders across requests, you need a persistent cache.
 
+### Caching persistently
+
+A persistent cache allows renders to be cached across multiple requests. This reduces the number of synchronous network requests to Jahuty's API and improves your application's average response time.
+
+To configure Jahuty to use your persistent cache, pass a cache implementation to the client via the `cache` configuration option:
+
+```ruby
+jahuty = new Jahuty::Client.new(
+  api_key: 'YOUR_API_KEY',
+  cache: cache
+)
+```
+
+The persistent cache implementation you choose and configure is up to you. There are many libraries available, and most frameworks provide their own. At this time, we support any object which responds to `get(key)`/`set(key, value, expires_in:)` or `read(key)`/`write(key, value, expires_in:)` including [ActiveSupport::Cache::Store](https://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html#method-i-fetch).
+
+### Expiring
+
+There are three methods for configuring this library's `:expires_in`, the amount of time between when a render is stored and when it's considered stale. From lowest-to-highest precedence, the methods are:
+
+1. configuring your caching implementation,
+1. configuring this library's default `:expires_in`, and
+1. configuring a render's `:expires_in`.
+
+#### Configuring your caching implementation
+
+You can usually configure your caching implementation with a default `:expires_in`. If no other `:expires_in` is configured, this library will defer to the caching implementation's default `:expires_in`.
+
+#### Configuring this library's default `:expires_in`
+
+You can configure a default `:expires_in` for all of this library's renders by passing an integer number of seconds via the client's `:expires_in` configuration option:
+
+```ruby
+jahuty = Jahuty::Client.new(
+  api_key: 'YOUR_API_KEY',
+  cache: cache,
+  expires_in: 60  # <- Cache all renders for sixty seconds
+)
+```
+
+If this library's default `:expires_in` is set, it will take precedence over the default `:expires_in` of the caching implementation.
+
+#### Configuring a render's `:expires_in`
+
+You can configure `:expires_in` for individual renders by passing an integer number of seconds via the render method's `:expires_in` configuration option:
+
+```ruby
+# Cache all renders 300 seconds (five minutes).
+jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY', cache: cache, expires_in: 300)
+
+# Except, cache this render for 60 seconds.
+render = jahuty.snippets.render YOUR_SNIPPET_ID, expires_in: 60
+
+# Except, cache the renders in this collection for 120 seconds.
+render = jahuty.snippets.all_renders 'YOUR_TAG', expires_in: 120
+```
+
+If a render's `:expires_in` is set, it will take precedence over the library's default `:expires_in` and the caching implementation's `:expires_in`.
+
+### Caching collections
+
+By default, this library will cache each render returned by `all_renders`:
+
+```ruby
+jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY', cache: cache)
+
+# Sends a network request, caches each render, and returns the collection.
+jahuty.snippets.all_renders 'YOUR_TAG';
+
+# If this reder exists in the collection, the cached value will be used instead
+# of sending a network request for the latest version.
+jahuty.snippets.render YOUR_SNIPPET_ID;
+```
+
+This is a powerful feature, especially when combined with a persistent cache. Using the `all_renders` method, you can render and cache an arbitrarily large chunk of content with a single network request. Because any subsequent call to `render` a snippet in the collection will use its cached version, you can reduce the number of network requests to load your content.
+
+This method is even more powerful when combined with an asynchronous background job. When `all_renders` can be called outside your request cycle periodically, you can turn your cache into your content storage mechanism. You can render and cache dynamic content as frequently as you like without any hit to your application's response time.
+
+### Disabling caching
+
+You can disable caching, even the default in-memory caching, by passing an `:expires_in` of zero (`0`) or a negative integer (e.g., `-1`) via any of the methods described above. For example:
+
+```ruby
+# Disable all caching.
+jahuty1 = Jahuty::Client.new(api_key: 'YOUR_API_KEY', expires_in: 0)
+
+# Disable caching for this render.
+jahuty2 = Jahuty::Client.new(api_key: 'YOUR_API_KEY', expires_in: 60)
+jahuty2.snippets.render 1, expires_in: 0
+```
+
+## Handling errors
+
+If an error occurs with [Jahuty's API](https://docs.jahuty.com/api#errors), a `Jahuty::Exception::Error` will be raised:
+
+```ruby
 begin
   jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
   jahuty.snippets.render YOUR_SNIPPET_ID

data/jahuty.gemspec

@@ -32,6 +32,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '~> 2.6'
 
   spec.add_dependency 'faraday', '~> 1.0'
+  spec.add_dependency 'mini_cache', '~> 1.1'
 
   spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'rake', '~> 12.3'

data/lib/jahuty.rb

@@ -3,10 +3,13 @@
 require 'jahuty/version'
 
 require 'jahuty/action/base'
+require 'jahuty/action/index'
 require 'jahuty/action/show'
 
 require 'jahuty/api/client'
 
+require 'jahuty/cache/facade'
+
 require 'jahuty/exception/error'
 
 require 'jahuty/request/base'
@@ -16,12 +19,15 @@ require 'jahuty/resource/problem'
 require 'jahuty/resource/render'
 require 'jahuty/resource/factory'
 
+require 'jahuty/response/handler'
+
 require 'jahuty/service/base'
 require 'jahuty/service/snippet'
-require 'jahuty/service/factory'
 
 require 'jahuty/client'
 
+require 'jahuty/util'
+
 module Jahuty
   BASE_URI = 'https://api.jahuty.com'
 end

data/lib/jahuty/action/index.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Jahuty
+  module Action
+    # Displays a collection of resources.
+    class Index < Base
+    end
+  end
+end

data/lib/jahuty/api/client.rb

@@ -20,10 +20,11 @@ module Jahuty
       def send(request)
         @client ||= Faraday.new(url: ::Jahuty::BASE_URI, headers: headers)
 
+        # Cnvert the action's string method to Faraday's verb-based methods.
         @client.send(
           request.method.to_sym,
           request.path,
-          { params: request.params }
+          request.params
         )
       end
 

data/lib/jahuty/cache/facade.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Jahuty
+  module Cache
+    # Abstracts away the differences in cache implementation methods and
+    # argument lists.
+    class Facade
+      def initialize(cache)
+        @cache = cache
+      end
+
+      def delete(key)
+        if @cache.respond_to? :delete
+          @cache.delete key
+        elsif @cache.respond_to? :unset
+          @cache.unset key
+        else
+          raise NoMethodError, 'Cache must respond to :delete or :unset'
+        end
+      end
+
+      def read(key)
+        if @cache.respond_to? :read
+          @cache.read key
+        elsif @cache.respond_to? :get
+          @cache.get key
+        else
+          raise NoMethodError, 'Cache must respond to :read or :get'
+        end
+      end
+
+      def write(key, value, expires_in: nil)
+        if Object.const_defined?('::ActiveSupport::Cache::Store') &&
+           @cache.is_a?(::ActiveSupport::Cache::Store)
+          @cache.write key, value, expires_in: expires_in, race_condition_ttl: 10
+        elsif @cache.respond_to? :write
+          @cache.write key, value, expires_in: expires_in
+        elsif @cache.respond_to? :set
+          @cache.set key, value, expires_in: expires_in
+        else
+          raise NoMethodError, 'Cache must respond to :write or :set'
+        end
+      end
+    end
+  end
+end

data/lib/jahuty/client.rb

@@ -1,17 +1,27 @@
 # frozen_string_literal: true
 
+require 'mini_cache'
+
 module Jahuty
   # Executes requests against Jahuty's API and returns resources.
   class Client
-    def initialize(api_key:)
-      @api_key  = api_key
-      @services = Service::Factory.new(client: self)
+    def initialize(api_key:, cache: nil, expires_in: nil, prefer_latest: false)
+      @api_key = api_key
+      @cache = Cache::Facade.new(cache || ::MiniCache::Store.new)
+      @expires_in = expires_in
+      @services = {}
+      @prefer_latest = prefer_latest
     end
 
-    # Allows services to appear as properties (e.g., jahuty.snippets).
+    # Allows services to be accessed as properties (e.g., jahuty.snippets).
     def method_missing(name, *args, &block)
-      if args.empty? && @services.respond_to?(name)
-        @services.send(name)
+      if args.empty? && name == :snippets
+        unless @services.key?(name)
+          @services[name] = Service::Snippet.new(
+            client: self, cache: @cache, expires_in: @expires_in, prefer_latest: @prefer_latest
+          )
+        end
+        @services[name]
       else
         super
       end
@@ -26,17 +36,17 @@ module Jahuty
 
       response = @client.send(request)
 
-      @resources ||= Resource::Factory.new
+      @responses ||= Response::Handler.new
 
-      resource = @resources.call(action, response)
+      result = @responses.call(action, response)
 
-      raise Exception::Error.new(resource), 'API responded with a problem' if resource.is_a?(Resource::Problem)
+      raise Exception::Error.new(result), 'API problem' if result.is_a?(Resource::Problem)
 
-      resource
+      result
     end
 
     def respond_to_missing?(name, include_private = false)
-      @services.respond_to?(name, include_private) || super
+      name == :snippets || super
     end
   end
 end

data/lib/jahuty/request/factory.rb

@@ -2,16 +2,28 @@
 
 module Jahuty
   module Request
-    # Instantiates a request from an action. Currently, this is elementary. As
-    # we add actions, it will become more complicated.
+    # Instantiates a request from an action.
     class Factory
       def call(action)
         Base.new(
           method: 'get',
-          path: "snippets/#{action.id}/render",
+          path: path(action),
           params: action.params
         )
       end
+
+      private
+
+      def path(action)
+        case action
+        when ::Jahuty::Action::Show
+          "snippets/#{action.id}/render"
+        when ::Jahuty::Action::Index
+          'snippets/render'
+        else
+          raise ArgumentError, 'Action is not supported'
+        end
+      end
     end
   end
 end

data/lib/jahuty/resource/factory.rb

@@ -1,31 +1,20 @@
 # frozen_string_literal: true
 
-require 'json'
-
 module Jahuty
   module Resource
-    # Negotiates the resource to return given the requested action and the
-    # server's response.
+    # Instantiates and returns a resource.
     class Factory
       CLASSES = {
         problem: Problem.name,
         render: Render.name
       }.freeze
 
-      def call(action, response)
-        if success? response
-          resource_name = action.resource
-        elsif problem? response
-          resource_name = 'problem'
-        else
-          raise ArgumentError, 'Unexpected response'
-        end
-
-        resource_class = class_name(resource_name.to_sym)
+      def call(resource_name, payload)
+        klass = class_name(resource_name.to_sym)
 
-        payload = parse(response)
+        raise ArgumentError, "#{resource_name} missing" if klass.nil?
 
-        Object.const_get(resource_class).send(:new, **payload)
+        Object.const_get(klass).send(:from, **payload)
       end
 
       private
@@ -33,18 +22,6 @@ module Jahuty
       def class_name(resource_name)
         CLASSES[resource_name.to_sym]
       end
-
-      def problem?(response)
-        response.headers['Content-Type'] == 'application/problem+json'
-      end
-
-      def parse(response)
-        JSON.parse(response.body, symbolize_names: true)
-      end
-
-      def success?(response)
-        response.status.between?(200, 299)
-      end
     end
   end
 end

data/lib/jahuty/resource/problem.rb

@@ -12,6 +12,14 @@ module Jahuty
         @type   = type
         @detail = detail
       end
+
+      def self.from(data)
+        raise ArgumentError.new, 'Key :status missing' unless data.key?(:status)
+        raise ArgumentError.new, 'Key :type missing' unless data.key?(:type)
+        raise ArgumentError.new, 'Key :detail missing' unless data.key?(:detail)
+
+        Problem.new(data.slice(:status, :type, :detail))
+      end
     end
   end
 end

data/lib/jahuty/resource/render.rb

@@ -2,14 +2,20 @@
 
 module Jahuty
   module Resource
-    # A snippet's rendered content. Remember, renders are unique by the
-    # combination of id and params (i.e., the same id can produce different
-    # renders with different params).
+    # A snippet's rendered content.
     class Render
-      attr_accessor :content
+      attr_accessor :content, :snippet_id
 
-      def initialize(content:)
+      def initialize(content:, snippet_id:)
         @content = content
+        @snippet_id = snippet_id
+      end
+
+      def self.from(data)
+        raise ArgumentError.new, 'Key :content missing' unless data.key?(:content)
+        raise ArgumentError.new, 'Key :snippet_id missing' unless data.key?(:snippet_id)
+
+        Render.new(data.slice(:content, :snippet_id))
       end
 
       def to_s

data/lib/jahuty/response/handler.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Jahuty
+  module Response
+    # Inspects the response and returns the appropriate resource or collection.
+    class Handler
+      def call(action, response)
+        resource_name = name_resource action, response
+
+        payload = parse response
+
+        @resources ||= ::Jahuty::Resource::Factory.new
+
+        if collection?(payload)
+          payload.map { |data| @resources.call resource_name, data }
+        elsif resource?(payload)
+          @resources.call resource_name, payload
+        else
+          raise ArgumentError, 'Action and payload mismatch'
+        end
+      end
+
+      private
+
+      def collection?(payload)
+        payload.is_a?(::Array)
+      end
+
+      def name_resource(action, response)
+        if success? response
+          action.resource
+        elsif problem? response
+          'problem'
+        else
+          raise ArgumentError, 'Unexpected response'
+        end
+      end
+
+      def parse(response)
+        JSON.parse(response.body, symbolize_names: true)
+      end
+
+      def problem?(response)
+        response.headers['Content-Type'].include?('application/problem+json') &&
+          (response.status < 200 || response.status >= 300)
+      end
+
+      def resource?(payload)
+        payload.is_a?(::Object)
+      end
+
+      def success?(response)
+        response.headers['Content-Type'].include?('application/json') &&
+          response.status.between?(200, 299)
+      end
+    end
+  end
+end

data/lib/jahuty/service/snippet.rb

@@ -4,16 +4,96 @@ module Jahuty
   module Service
     # A service for interacting with snippets.
     class Snippet < Base
-      def render(id, options = {})
-        params = { params: options[:params].to_json } unless options[:params].nil?
+      def initialize(client:, cache:, expires_in: nil, prefer_latest: false)
+        super(client: client)
+
+        @cache = cache
+        @expires_in = expires_in
+        @prefer_latest = prefer_latest
+      end
+
+      def all_renders(tag, params: {}, expires_in: @expires_in, prefer_latest: @prefer_latest)
+        renders = index_renders tag: tag, params: params, prefer_latest: prefer_latest
+
+        cache_renders renders: renders, params: params, expires_in: expires_in
+
+        renders
+      end
+
+      def render(snippet_id, params: {}, expires_in: @expires_in, prefer_latest: @prefer_latest)
+        key = cache_key snippet_id: snippet_id, params: params
+
+        render = @cache.read(key)
+
+        @cache.delete key unless render.nil? || cacheable?(expires_in)
+
+        if render.nil?
+          render = show_render snippet_id: snippet_id, params: params, prefer_latest: prefer_latest
+
+          @cache.write key, render, expires_in: expires_in if cacheable?(expires_in)
+        end
+
+        render
+      end
+
+      private
+
+      def cache_key(snippet_id:, params: {})
+        fingerprint = Digest::MD5.new
+        fingerprint << "snippets/#{snippet_id}/render/"
+        fingerprint << params.to_json
+
+        "jahuty_#{fingerprint.hexdigest}"
+      end
+
+      def cache_renders(renders:, params:, expires_in: nil)
+        expires_in ||= @expires_in
+
+        return if renders.nil?
+
+        return unless cacheable?(expires_in)
+
+        global_params = params['*'] || {}
+
+        renders.each do |render|
+          local_params = params[render.snippet_id.to_s] || {}
+          render_params = ::Jahuty::Util.deep_merge global_params, local_params
+
+          key = cache_key snippet_id: render.snippet_id, params: render_params
+
+          @cache.write key, render, expires_in: expires_in
+        end
+      end
+
+      def cacheable?(expires_in)
+        expires_in.nil? || expires_in.positive?
+      end
+
+      def index_renders(tag:, params: {}, prefer_latest: false)
+        request_params = { tag: tag }
+        request_params[:params] = params.to_json unless params.empty?
+        request_params[:latest] = 1 if prefer_latest
+
+        action = ::Jahuty::Action::Index.new(
+          resource: 'render',
+          params: request_params
+        )
+
+        @client.request action
+      end
+
+      def show_render(snippet_id:, params: {}, prefer_latest: false)
+        request_params = {}
+        request_params[:params] = params.to_json unless params.empty?
+        request_params[:latest] = 1 if prefer_latest
 
         action = ::Jahuty::Action::Show.new(
-          id: id,
+          id: snippet_id,
           resource: 'render',
-          params: params || {}
+          params: request_params
         )
 
-        @client.request(action)
+        @client.request action
       end
     end
   end

data/lib/jahuty/util.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Jahuty
+  # Utility methods.
+  class Util
+    # Deeply merges two hashes like Rails.
+    #
+    # Ideally, the API and this library could use the same method to merge
+    # parameters. This library's method just needs to be deterministic and not
+    # collide distinct combinations.
+    #
+    # @see  https://github.com/rails/rails/blob/main/activesupport/lib/active_support/core_ext/hash/deep_merge.rb
+    def self.deep_merge(first_hash, other_hash, &block)
+      first_hash.merge!(other_hash) do |key, first_val, other_val|
+        if first_val.is_a?(Hash) && other_val.is_a?(Hash)
+          deep_merge(first_val, other_val, &block)
+        elsif block
+          yield(key, first_val, other_val)
+        else
+          other_val
+        end
+      end
+    end
+  end
+end

data/lib/jahuty/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jahuty
-  VERSION = '3.0.0'
+  VERSION = '3.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jahuty
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.3.0
 platform: ruby
 authors:
 - Jack Clayton
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-12-30 00:00:00.000000000 Z
+date: 2021-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: mini_cache
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -185,8 +199,10 @@ files:
 - jahuty.gemspec
 - lib/jahuty.rb
 - lib/jahuty/action/base.rb
+- lib/jahuty/action/index.rb
 - lib/jahuty/action/show.rb
 - lib/jahuty/api/client.rb
+- lib/jahuty/cache/facade.rb
 - lib/jahuty/client.rb
 - lib/jahuty/exception/error.rb
 - lib/jahuty/request/base.rb
@@ -194,9 +210,10 @@ files:
 - lib/jahuty/resource/factory.rb
 - lib/jahuty/resource/problem.rb
 - lib/jahuty/resource/render.rb
+- lib/jahuty/response/handler.rb
 - lib/jahuty/service/base.rb
-- lib/jahuty/service/factory.rb
 - lib/jahuty/service/snippet.rb
+- lib/jahuty/util.rb
 - lib/jahuty/version.rb
 homepage: https://www.jahuty.com
 licenses:
@@ -221,7 +238,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: Jahuty's Ruby SDK.

data/lib/jahuty/service/factory.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-module Jahuty
-  module Service
-    # Instantiates the requested service and memoizes it for subsequent
-    # requests.
-    class Factory
-      CLASSES = {
-        snippets: Snippet.name
-      }.freeze
-
-      def initialize(client:)
-        @client   = client
-        @services = {}
-      end
-
-      def method_missing(name, *args, &block)
-        if args.empty? && class_name?(name)
-          unless @services.key?(name)
-            klass   = class_name(name)
-            service = Object.const_get(klass).send(:new, client: @client)
-            @services[name] = service
-          end
-
-          @services[name]
-        else
-          super
-        end
-      end
-
-      def respond_to_missing?(name, include_private = false)
-        class_name(name) || super
-      end
-
-      private
-
-      def class_name(service_name)
-        CLASSES[service_name]
-      end
-
-      def class_name?(service_name)
-        CLASSES.key?(service_name)
-      end
-    end
-  end
-end