jahuty 2.0.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b9d03742760e8a4ef3d3a0e25d10c1d1327ee3604ce18333d1e65fe782724d1
-  data.tar.gz: 31b7447e69c911a50526675432d218514e2b71b577ad57848d7d644ba39fdba6
+  metadata.gz: 42d427523be1564e07087d282367b7c13b9e80ac7219522a26a86a04f6fd23e7
+  data.tar.gz: 5f164380a18fda536c08c918dbfaaba6aaffc02183cfb2e74c6944b3e0bc42c3
 SHA512:
-  metadata.gz: e75e3ec04864d5ef00f7ccf6887ed35dda5dcb7b7f817c2314c07bfa7b5579df6ae704cf8d92813d81f4a55eb86b1695d1288410298b60bb68dbb7ea8560e105
-  data.tar.gz: b453b5e32687e62dfbaf4ab62bd9463736c871e91fcbaeaecdc91afa738746823746c933974d86588719e1dd498e3f744020aa6f2955bece54e3c0c8f6f25924
+  metadata.gz: f5b8c35c587b3f26a7fce8830963c98c859307e444edf5a0b058695e954fc5ce1dd0220b25f99d874ed983f1c72474546b51a2294f718bbea0358198d01ce6f6
+  data.tar.gz: 6f037d7ee49936532c2bd2ed5ed6f91942352f95082da4af28bd390afd3bc0d0dfdcda847f2c4e4ad742e4b1702562c9c6cba6c0fd5df4c923756c4113aa3d6a

data/.circleci/config.yml

@@ -0,0 +1,33 @@
+version: 2.1
+orbs:
+  ruby: circleci/ruby@0.1.2
+  codecov: codecov/codecov@1.1.3
+jobs:
+  build:
+    docker:
+      - image: circleci/ruby:2.6.3-stretch-node
+    executor: ruby/default
+    steps:
+      - checkout
+      - run:
+          name: Update bundler
+          command: gem install bundler
+      - run:
+          name: Which bundler?
+          command: bundle -v
+      - ruby/bundle-install
+      - run:
+          name: Run rubocop
+          command: bundle exec rake rubocop
+      - run:
+          name: Run specs
+          command: |
+            bundle exec rspec --profile 10 \
+                              --format RspecJunitFormatter \
+                              --out test_results/rspec.xml \
+                              --format progress \
+                              $(circleci tests glob "spec/**/*_spec.rb" | circleci tests split --split-by=timings)
+      - store_test_results:
+          path: test_results
+      - codecov/upload:
+          file: ./coverage/coverage.xml

data/.rubocop.yml

@@ -0,0 +1,15 @@
+require:
+ - rubocop-performance
+ - rubocop-rspec
+AllCops:
+  TargetRubyVersion: 2.6
+  NewCops: enable
+Metrics/BlockLength:
+  Exclude:
+    - 'jahuty.gemspec'
+    - 'Rakefile'
+    - '**/*.rake'
+    - 'spec/**/*.rb'
+Metrics/ModuleLength:
+  Exclude:
+    - 'spec/**/*.rb'

data/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.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.
+- Change `README` and fix broken links from `www.jahuty.com/docs` to `docs.jahuty.com`.
+- Add [CircleCI](https://circleci.com/gh/jahuty/jahuty-ruby) continuous integration.
+- Add [Rubocop](https://github.com/rubocop-hq/rubocop) code analyzer and formatter, based on the community style guide.
+- Add code coverage analysis with [Simplecov](https://github.com/simplecov-ruby/simplecov) and [Codecov.io](https://codecov.io/gh/jahuty/jahuty-ruby).
+
 ## 2.0.0 - 2020-07-04
 
 - Change `Service::Get` to `Service::Render`.

data/Gemfile

@@ -1,4 +1,6 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in jahuty.gemspec
 gemspec

data/README.md

@@ -1,96 +1,233 @@
+[![CircleCI](https://circleci.com/gh/jahuty/jahuty-ruby.svg?style=svg)](https://circleci.com/gh/jahuty/jahuty-ruby) [![codecov](https://codecov.io/gh/jahuty/jahuty-ruby/branch/master/graph/badge.svg?token=NLDCGGYB8S)](https://codecov.io/gh/jahuty/jahuty-ruby) [![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop-hq/rubocop)
+
 # jahuty-ruby
-Welcome to [Jahuty's](https://www.jahuty.com) Ruby SDK!
+
+Welcome to the [Ruby SDK](https://docs.jahuty.com/sdks/ruby) for [Jahuty's API](https://docs.jahuty.com/api)!
 
 ## Installation
 
-This library requires [Ruby 2.3+](https://www.ruby-lang.org/en/downloads/releases/).
+This library requires [Ruby 2.6+](https://www.ruby-lang.org/en/downloads/releases/).
 
 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", "~> 2.0"
-```
-
-And then execute:
-
-```bash
-$ bundle
+gem 'jahuty', '~> 3.1'
 ```
 
 ## Usage
 
-Before use, the library needs to be configured with your [API key](https://www.jahuty.com/docs/api#authentication) (ideally, once during startup):
+Instantiate the client with your [API key](https://docs.jahuty.com/api#authentication) and use `snippets.render` to render your snippet:
 
 ```ruby
-require "jahuty"
+jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
 
-Jahuty.key = "YOUR_API_KEY"
+puts jahuty.snippets.render YOUR_SNIPPET_ID
 ```
 
-With the API key set, you can use the `Snippet.render` method to render a snippet:
+You can access the render's content with `to_s` or `content`:
 
 ```ruby
-require "jahuty"
+jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
 
-# retrieve the snippet
-render = Snippet.render YOUR_SNIPPET_ID
+render = jahuty.snippets.render YOUR_SNIPPET_ID
 
-# convert it to a string
-render.to_s
+a = render.to_s
 
-# or, access its attributes
-render.content
+b = render.content
+
+a == b  # returns true
 ```
 
 In an HTML view:
 
 ```html+erb
-<%-
-require "jahuty"  
-
-Jahuty.key = "YOUR_API_KEY"
-%>
+<%- jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY') -%>
 <!doctype html>
 <html>
 <head>
     <title>Awesome example</title>
 </head>
 <body>
-    <%= Snippet.render YOUR_SNIPPET_ID %>
+    <%== jahuty.snippets.render YOUR_SNIPPET_ID %>
 </body>
 ```
 
+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 }
+```
+
 ## Parameters
 
-You can [pass parameters](https://www.jahuty.com/docs/passing-a-parameter) into your snippet using the `params` key of the options hash:
+You can [pass parameters](https://docs.jahuty.com/liquid/parameters) into your renders using the `params` option:
 
 ```ruby
-require "jahuty"
+jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
 
-Snippet.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 variables](https://www.jahuty.com/docs/assigning-a-variable) below in your snippet:
+The parameters above would be equivalent to [assigning the variable](https://docs.jahuty.com/liquid/variables) below in your snippet:
 
 ```html
 {% assign foo = "bar" %}
 ```
 
-## Errors
+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' }
+}
+```
 
-If you don't set your API key before calling `Snippet.render`, a `StandardError` will be raised. If an error occurs with [Jahuty's API](https://www.jahuty.com/docs/api), a `NotOk` exception will be raised:
+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
+
+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
+```
+
+## Errors
+
+If an error occurs with [Jahuty's API](https://docs.jahuty.com/api#errors), a `Jahuty::Exception::Error` will be raised:
+
+```ruby
 begin
-  Snippet.render YOUR_SNIPPET_ID
-rescue StandardError => e
-  # hmm, did you set the API key first?
-rescue Jahuty::Exception::NotOk => e
-  # hmm, the API returned something besides 2xx status code
+  jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
+  jahuty.snippets.render YOUR_SNIPPET_ID
+rescue Jahuty::Exception::Error => e
+  # The API returned an error. See the error's problem for details.
   puts e.problem.type    # a URL to more information
   puts e.problem.status  # the status code
   puts e.problem.detail  # a description of the error

data/Rakefile

@@ -1,6 +1,14 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec
+
+RuboCop::RakeTask.new do |task|
+  task.requires << 'rubocop-performance'
+  task.requires << 'rubocop-rspec'
+end

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "jahuty/snippets"
+require 'bundler/setup'
+require 'jahuty/snippets'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +11,5 @@ require "jahuty/snippets"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/bin/setup

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# frozen_string_literal: true
+
 set -euo pipefail
 IFS=$'\n\t'
 set -vx

data/jahuty.gemspec

@@ -1,30 +1,47 @@
+# frozen_string_literal: true
 
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
-require "jahuty"
+require 'jahuty/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "jahuty"
+  spec.name          = 'jahuty'
   spec.version       = Jahuty::VERSION
-  spec.authors       = ["Jack Clayton"]
-  spec.email         = ["jack@jahuty.com"]
+  spec.authors       = ['Jack Clayton']
+  spec.email         = ['jack@jahuty.com']
 
-  spec.summary       = %q{Jahuty's Ruby SDK.}
-  spec.description   = %q{Turn any page into a content-managed page.}
-  spec.homepage      = "https://github.com/jahuty/jahuty-ruby"
-  spec.license       = "MIT"
+  spec.summary       = 'Jahuty\'s Ruby SDK.'
+  spec.description   = 'Turn any page into a content-managed page.'
+  spec.homepage      = 'https://www.jahuty.com'
+  spec.license       = 'MIT'
 
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/jahuty/jahuty-ruby'
+  spec.metadata['changelog_uri'] = 'https://github.com/jahuty/jahuty-ruby/blob/master/CHANGELOG.md'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '~> 2.6'
 
-  spec.add_dependency "faraday", "~> 1.0"
+  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"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 12.3'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rspec_junit_formatter', '~>0.4'
+  spec.add_development_dependency 'rubocop', '~> 1.7'
+  spec.add_development_dependency 'rubocop-performance', '~> 1.9'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.1'
+  spec.add_development_dependency 'simplecov', '~>0.20'
+  spec.add_development_dependency 'simplecov-cobertura', '~> 1.4'
+  spec.add_development_dependency 'webmock', '~> 3.11'
 end