i18n-backend-http 0.1.0

data/.travis.yml

@@ -0,0 +1,5 @@
+script: "bundle exec rake"
+rvm:
+  - ree
+  - 1.9.2
+  - 1.9.3

data/Appraisals

@@ -0,0 +1,7 @@
+appraise "rails2" do
+  gem 'i18n', '~>0.4.0'
+end
+
+appraise "rails3" do
+  gem 'i18n'
+end

data/Gemfile

@@ -0,0 +1,11 @@
+source :rubygems
+gemspec
+
+gem 'rake'
+gem 'shoulda'
+gem 'vcr'
+gem 'webmock'
+gem 'mocha'
+gem 'appraisal'
+gem 'mynyml-redgreen'
+gem 'json'

data/Gemfile.lock

@@ -0,0 +1,52 @@
+PATH
+  remote: .
+  specs:
+    i18n-backend-http (0.1.0)
+      faraday
+      gem_of_thrones
+      i18n
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.2.8)
+    appraisal (0.4.1)
+      bundler
+      rake
+    crack (0.3.1)
+    faraday (0.8.0)
+      multipart-post (~> 1.1)
+    gem_of_thrones (0.2.1)
+    i18n (0.6.0)
+    json (1.7.1)
+    metaclass (0.0.1)
+    mocha (0.11.4)
+      metaclass (~> 0.0.1)
+    multipart-post (1.1.5)
+    mynyml-redgreen (0.7.1)
+      term-ansicolor (>= 1.0.4)
+    rake (0.9.2)
+    shoulda (3.0.1)
+      shoulda-context (~> 1.0.0)
+      shoulda-matchers (~> 1.0.0)
+    shoulda-context (1.0.0)
+    shoulda-matchers (1.0.0)
+    term-ansicolor (1.0.7)
+    vcr (2.1.1)
+    webmock (1.8.6)
+      addressable (>= 2.2.7)
+      crack (>= 0.1.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  appraisal
+  i18n-backend-http!
+  json
+  mocha
+  mynyml-redgreen
+  rake
+  shoulda
+  vcr
+  webmock

data/Rakefile

@@ -0,0 +1,30 @@
+require 'appraisal'
+require 'bundler/gem_tasks'
+
+task :default do
+  sh "bundle exec rake appraisal:install && bundle exec rake appraisal test"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+# extracted from https://github.com/grosser/project_template
+rule /^version:bump:.*/ do |t|
+  sh "git status | grep 'nothing to commit'" # ensure we are not dirty
+  index = ['major', 'minor','patch'].index(t.name.split(':').last)
+  file = 'lib/i18n/backend/http/version.rb'
+
+  version_file = File.read(file)
+  old_version, *version_parts = version_file.match(/(\d+)\.(\d+)\.(\d+)/).to_a
+  version_parts[index] = version_parts[index].to_i + 1
+  version_parts[2] = 0 if index < 2 # remove patch for minor
+  version_parts[1] = 0 if index < 1 # remove minor for major
+  new_version = version_parts * '.'
+  File.open(file,'w'){|f| f.write(version_file.sub(old_version, new_version)) }
+
+  sh "bundle && git add #{file} Gemfile.lock && git commit -m 'bump version to #{new_version}'"
+end

data/Readme.md

@@ -0,0 +1,84 @@
+Rails I18n Backend for Http APIs with etag-aware distributed background polling and lru-memory+[memcache] caching.<br/>
+Very few request, always up to date + fast.
+
+Install
+=======
+
+    gem install i18n-backend-http
+Or
+
+    rails plugin install git://github.com/grosser/i18n-backend-http.git
+
+Usage
+=====
+
+```Ruby
+class MyBackend < I18n::Backend::Http
+  def initialize(options={})
+    super({
+      :host => "https://api.host.com",
+      :cache => Rails.cache,
+      :http_open_timeout => 5, # default: 1
+      :http_read_timeout => 5, # default: 1
+      # :exception_handler => lambda{|e| Rails.logger.error e },
+      # :memory_cache_size => ??, # default: 10 locales
+    }.merge(options))
+  end
+
+  def parse_response(body)
+    JSON.load(body)["translations"]
+  end
+
+  def path(locale)
+    "/path/to/api/#{locale}.json"
+  end
+end
+
+I18n.backend = MyBackend.new
+```
+
+### Polling
+Tries to update all used translations every 10 minutes (using ETag and :cache), can be stopped via `I18n.backend.stop_polling`.<br/>
+If a :cache is given, all backends pick one master to do the polling, all others refresh from :cache
+
+```Ruby
+I18n.backend = MyBackend.new(:polling_interval => 30.minutes, :cache => Rails.cache)
+
+I18n.t('some.key') == "Old value"
+# change in backend + wait 30 minutes
+I18n.t('some.key') == "New value"
+```
+
+### :cache
+If you pass `:cache => Rails.cache`, translations will be loaded from cache and updated in the cache.<br/>
+The cache **MUST** support :unless_exist, so [gem_of_thrones](https://github.com/grosser/gem_of_thrones) can do its job,<br/>
+MemCacheStore + LibMemCacheStore + ActiveSupport::Cache::MemoryStore (edge) work.
+
+### Exceptions
+To handle http exceptions provide e.g. `:exception_handler => lambda{|e| puts e }` (prints to stderr by default).
+
+### Limited memory cache
+The backend stores the 10 least recently used locales in memory, if you want to mess with this `:memory_cache_size => 100`
+
+### Fallback
+If the http backend is down, it does not translate, but also does not constantly try to query -> your app is untranslated but not down.</br>
+You should either use :default for all I18n.t or use a Chain, so when http is down e.g. english is used.
+
+```Ruby
+I18n.backend = I18n::Backend::Chain.new(
+  MyBackend.new(options),
+  I18n::Backend::Simple.new
+)
+```
+
+TODO
+====
+ - available_locales is not implemented, since we did not need it
+ - `reload` -> all caches should be cleared
+
+Author
+======
+[Michael Grosser](http://grosser.it)<br/>
+michael@grosser.it<br/>
+License: MIT<br/>
+[![Build Status](https://secure.travis-ci.org/grosser/i18n-backend-http.png)](http://travis-ci.org/grosser/i18n-backend-http)

data/gemfiles/rails2.gemfile

@@ -0,0 +1,15 @@
+# This file was generated by Appraisal
+
+source :rubygems
+
+gem "rake"
+gem "shoulda"
+gem "vcr"
+gem "webmock"
+gem "mocha"
+gem "appraisal"
+gem "mynyml-redgreen"
+gem "json"
+gem "i18n", "~>0.4.0"
+
+gemspec :path=>"../"

data/gemfiles/rails2.gemfile.lock

@@ -0,0 +1,53 @@
+PATH
+  remote: /Users/mgrosser/code/tools/i18n-backend-http
+  specs:
+    i18n-backend-http (0.0.1)
+      faraday
+      gem_of_thrones
+      i18n
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.2.8)
+    appraisal (0.4.1)
+      bundler
+      rake
+    crack (0.3.1)
+    faraday (0.8.0)
+      multipart-post (~> 1.1)
+    gem_of_thrones (0.2.1)
+    i18n (0.4.2)
+    json (1.7.1)
+    metaclass (0.0.1)
+    mocha (0.11.4)
+      metaclass (~> 0.0.1)
+    multipart-post (1.1.5)
+    mynyml-redgreen (0.7.1)
+      term-ansicolor (>= 1.0.4)
+    rake (0.9.2.2)
+    shoulda (3.0.1)
+      shoulda-context (~> 1.0.0)
+      shoulda-matchers (~> 1.0.0)
+    shoulda-context (1.0.0)
+    shoulda-matchers (1.0.0)
+    term-ansicolor (1.0.7)
+    vcr (2.1.1)
+    webmock (1.8.7)
+      addressable (>= 2.2.7)
+      crack (>= 0.1.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  appraisal
+  i18n (~> 0.4.0)
+  i18n-backend-http!
+  json
+  mocha
+  mynyml-redgreen
+  rake
+  shoulda
+  vcr
+  webmock

data/gemfiles/rails3.gemfile

@@ -0,0 +1,15 @@
+# This file was generated by Appraisal
+
+source :rubygems
+
+gem "rake"
+gem "shoulda"
+gem "vcr"
+gem "webmock"
+gem "mocha"
+gem "appraisal"
+gem "mynyml-redgreen"
+gem "json"
+gem "i18n"
+
+gemspec :path=>"../"

data/gemfiles/rails3.gemfile.lock

@@ -0,0 +1,53 @@
+PATH
+  remote: /Users/mgrosser/code/tools/i18n-backend-http
+  specs:
+    i18n-backend-http (0.0.1)
+      faraday
+      gem_of_thrones
+      i18n
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.2.8)
+    appraisal (0.4.1)
+      bundler
+      rake
+    crack (0.3.1)
+    faraday (0.8.0)
+      multipart-post (~> 1.1)
+    gem_of_thrones (0.2.1)
+    i18n (0.6.0)
+    json (1.7.1)
+    metaclass (0.0.1)
+    mocha (0.11.4)
+      metaclass (~> 0.0.1)
+    multipart-post (1.1.5)
+    mynyml-redgreen (0.7.1)
+      term-ansicolor (>= 1.0.4)
+    rake (0.9.2.2)
+    shoulda (3.0.1)
+      shoulda-context (~> 1.0.0)
+      shoulda-matchers (~> 1.0.0)
+    shoulda-context (1.0.0)
+    shoulda-matchers (1.0.0)
+    term-ansicolor (1.0.7)
+    vcr (2.1.1)
+    webmock (1.8.7)
+      addressable (>= 2.2.7)
+      crack (>= 0.1.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  appraisal
+  i18n
+  i18n-backend-http!
+  json
+  mocha
+  mynyml-redgreen
+  rake
+  shoulda
+  vcr
+  webmock

data/i18n-backend-http.gemspec

@@ -0,0 +1,15 @@
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+name = "i18n-backend-http"
+require "i18n/backend/http/version"
+
+Gem::Specification.new(name, I18n::Backend::Http::VERSION) do |s|
+  s.summary = "Rails I18n Backend for Http APIs with etag-aware background polling and memory+[memcache] caching"
+  s.authors = ["Michael Grosser"]
+  s.email = "michael@grosser.it"
+  s.homepage = "http://github.com/grosser/#{name}"
+  s.files = `git ls-files`.split("\n")
+  s.license = 'MIT'
+  s.add_runtime_dependency "i18n"
+  s.add_runtime_dependency "gem_of_thrones"
+  s.add_runtime_dependency "faraday"
+end

data/lib/i18n/backend/http.rb

@@ -0,0 +1,114 @@
+require 'i18n'
+require 'i18n/backend/transliterator'
+require 'i18n/backend/base'
+require 'gem_of_thrones'
+require 'i18n/backend/http/version'
+require 'i18n/backend/http/etag_http_client'
+require 'i18n/backend/http/null_cache'
+require 'i18n/backend/http/lru_cache'
+
+module I18n
+  module Backend
+    class Http
+      include ::I18n::Backend::Base
+
+      def initialize(options)
+        @options = {
+          :http_open_timeout => 1,
+          :http_read_timeout => 1,
+          :polling_interval => 10*60,
+          :cache => NullCache.new,
+          :poll => true,
+          :exception_handler => lambda{|e| $stderr.puts e },
+          :memory_cache_size => 10,
+        }.merge(options)
+
+        @http_client = EtagHttpClient.new(@options)
+        @translations = LRUCache.new(@options[:memory_cache_size])
+        start_polling if @options[:poll]
+      end
+
+      def stop_polling
+        @stop_polling = true
+      end
+
+      protected
+
+      def start_polling
+        Thread.new do
+          until @stop_polling
+            sleep(@options[:polling_interval])
+            update_caches
+          end
+        end
+      end
+
+      def lookup(locale, key, scope = [], options = {})
+        key = ::I18n.normalize_keys(locale, key, scope, options[:separator])[1..-1].join('.')
+        translations(locale)[key]
+      end
+
+      def translations(locale)
+        @translations[locale] ||= (
+          translations_from_cache(locale) ||
+          download_and_cache_translations(locale)
+        )
+      end
+
+      def update_caches
+        @translations.keys.each do |locale|
+          if @options[:cache].is_a?(NullCache)
+            download_and_cache_translations(locale)
+          else
+            locked_update_cache(locale)
+          end
+        end
+      end
+
+      def locked_update_cache(locale)
+        @aspirants ||= {}
+        aspirant = @aspirants[locale] ||= GemOfThrones.new(
+          :cache => @options[:cache],
+            :timeout => (@options[:polling_interval] * 3).ceil,
+            :cache_key => "i18n/backend/http/locked_update_caches/#{locale}"
+        )
+        if aspirant.rise_to_power
+          download_and_cache_translations(locale)
+        else
+          update_memory_cache_from_cache(locale)
+        end
+      end
+
+      def update_memory_cache_from_cache(locale)
+        @translations[locale] = translations_from_cache(locale)
+      end
+
+      def translations_from_cache(locale)
+        @options[:cache].read(cache_key(locale))
+      end
+
+      def cache_key(locale)
+        "i18n/backend/http/translations/#{locale}"
+      end
+
+      def download_and_cache_translations(locale)
+        @http_client.download(path(locale)) do |result|
+          translations = parse_response(result)
+          @options[:cache].write(cache_key(locale), translations)
+          @translations[locale] = translations
+        end
+      rescue => e
+        @options[:exception_handler].call(e)
+        @translations[locale] = {} # do not write distributed cache
+      end
+
+      def parse_response(body)
+        raise "implement parse_response"
+      end
+
+      def path(locale)
+        raise "implement path"
+      end
+    end
+  end
+end