copy_tuner_client 0.0.1

data/lib/copy_tuner_client/client.rb

@@ -0,0 +1,136 @@
+require 'net/http'
+require 'net/https'
+require 'copy_tuner_client/errors'
+
+module CopyTunerClient
+  # Communicates with the CopyTuner server. This class is used to actually
+  # download and upload blurbs, as well as issuing deploys.
+  #
+  # A client is usually instantiated when {Configuration#apply} is called, and
+  # the application will not need to interact with it directly.
+  class Client
+    # These errors will be rescued when connecting CopyTuner.
+    HTTP_ERRORS = [Timeout::Error, Errno::EINVAL, Errno::ECONNRESET, EOFError,
+                   Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError,
+                   Net::ProtocolError, SocketError, OpenSSL::SSL::SSLError,
+                   Errno::ECONNREFUSED]
+
+    # Usually instantiated from {Configuration#apply}. Copies options.
+    # @param options [Hash]
+    # @option options [String] :api_key API key of the project to connect to
+    # @option options [Fixnum] :port the port to connect to
+    # @option options [Boolean] :public whether to download draft or published content
+    # @option options [Fixnum] :http_read_timeout how long to wait before timing out when reading data from the socket
+    # @option options [Fixnum] :http_open_timeout how long to wait before timing out when opening the socket
+    # @option options [Boolean] :secure whether to use SSL
+    # @option options [Logger] :logger where to log transactions
+    # @option options [String] :ca_file path to root certificate file for ssl verification
+    def initialize(options)
+      [:api_key, :host, :port, :public, :http_read_timeout,
+        :http_open_timeout, :secure, :logger, :ca_file].each do |option|
+        instance_variable_set "@#{option}", options[option]
+      end
+    end
+
+    # Downloads all blurbs for the given api_key.
+    #
+    # If the +public+ option was set to +true+, this will use published blurbs.
+    # Otherwise, draft content is fetched.
+    #
+    # The client tracks ETags between download requests, and will return
+    # without yielding anything if the server returns a not modified response.
+    #
+    # @yield [Hash] downloaded blurbs
+    # @raise [ConnectionError] if the connection fails
+    def download
+      connect do |http|
+        request = Net::HTTP::Get.new(uri(download_resource))
+        request['If-None-Match'] = @etag
+        response = http.request(request)
+
+        if check response
+          log 'Downloaded translations'
+          yield JSON.parse(response.body)
+        else
+          log 'No new translations'
+        end
+
+        @etag = response['ETag']
+      end
+    end
+
+    # Uploads the given hash of blurbs as draft content.
+    # @param data [Hash] the blurbs to upload
+    # @raise [ConnectionError] if the connection fails
+    def upload(data)
+      connect do |http|
+        response = http.post(uri('draft_blurbs'), data.to_json, 'Content-Type' => 'application/json')
+        check response
+        log 'Uploaded missing translations'
+      end
+    end
+
+    # Issues a deploy, marking all draft content as published for this project.
+    # @raise [ConnectionError] if the connection fails
+    def deploy
+      connect do |http|
+        response = http.post(uri('deploys'), '')
+        check response
+        log 'Deployed'
+      end
+    end
+
+    private
+
+    attr_reader :host, :port, :api_key, :http_read_timeout,
+      :http_open_timeout, :secure, :logger, :ca_file
+
+    def public?
+      @public
+    end
+
+    def uri(resource)
+      "/api/v2/projects/#{api_key}/#{resource}"
+    end
+
+    def download_resource
+      if public?
+        'published_blurbs'
+      else
+        'draft_blurbs'
+      end
+    end
+
+    def connect
+      http = Net::HTTP.new(host, port)
+      http.open_timeout = http_open_timeout
+      http.read_timeout = http_read_timeout
+      http.use_ssl = secure
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      http.ca_file = ca_file
+
+      begin
+        yield http
+      rescue *HTTP_ERRORS => exception
+        raise ConnectionError, "#{exception.class.name}: #{exception.message}"
+      end
+    end
+
+    def check(response)
+      case response
+      when Net::HTTPNotFound
+        raise InvalidApiKey, "Invalid API key: #{api_key}"
+      when Net::HTTPNotModified
+        false
+      when Net::HTTPSuccess
+        true
+      else
+        raise ConnectionError, "#{response.code}: #{response.body}"
+      end
+    end
+
+    def log(message)
+      logger.info message
+    end
+  end
+end

data/lib/copy_tuner_client/configuration.rb

@@ -0,0 +1,224 @@
+require 'logger'
+require 'copy_tuner_client/i18n_backend'
+require 'copy_tuner_client/client'
+require 'copy_tuner_client/cache'
+require 'copy_tuner_client/process_guard'
+require 'copy_tuner_client/poller'
+require 'copy_tuner_client/prefixed_logger'
+require 'copy_tuner_client/request_sync'
+
+module CopyTunerClient
+  # Used to set up and modify settings for the client.
+  class Configuration
+
+    # These options will be present in the Hash returned by {#to_hash}.
+    OPTIONS = [:api_key, :development_environments, :environment_name, :host,
+        :http_open_timeout, :http_read_timeout, :client_name, :client_url,
+        :client_version, :port, :protocol, :proxy_host, :proxy_pass,
+        :proxy_port, :proxy_user, :secure, :polling_delay, :logger,
+        :framework, :middleware, :ca_file].freeze
+
+    # @return [String] The API key for your project, found on the project edit form.
+    attr_accessor :api_key
+
+    # @return [String] The host to connect to (defaults to +copy-tuner.com+).
+    attr_accessor :host
+
+    # @return [Fixnum] The port on which your CopyTuner server runs (defaults to +443+ for secure connections, +80+ for insecure connections).
+    attr_accessor :port
+
+    # @return [Boolean] +true+ for https connections, +false+ for http connections.
+    attr_accessor :secure
+
+    # @return [Fixnum] The HTTP open timeout in seconds (defaults to +2+).
+    attr_accessor :http_open_timeout
+
+    # @return [Fixnum] The HTTP read timeout in seconds (defaults to +5+).
+    attr_accessor :http_read_timeout
+
+    # @return [String, NilClass] The hostname of your proxy server (if using a proxy)
+    attr_accessor :proxy_host
+
+    # @return [String, Fixnum] The port of your proxy server (if using a proxy)
+    attr_accessor :proxy_port
+
+    # @return [String, NilClass] The username to use when logging into your proxy server (if using a proxy)
+    attr_accessor :proxy_user
+
+    # @return [String, NilClass] The password to use when logging into your proxy server (if using a proxy)
+    attr_accessor :proxy_pass
+
+    # @return [Array<String>] A list of environments in which content should be editable
+    attr_accessor :development_environments
+
+    # @return [Array<String>] A list of environments in which the server should not be contacted
+    attr_accessor :test_environments
+
+    # @return [String] The name of the environment the application is running in
+    attr_accessor :environment_name
+
+    # @return [String] The name of the client library being used to send notifications (defaults to +CopyTuner Client+)
+    attr_accessor :client_name
+
+    # @return [String, NilClass] The framework notifications are being sent from, if any (such as +Rails 2.3.9+)
+    attr_accessor :framework
+
+    # @return [String] The version of the client library being used to send notifications (such as +1.0.2+)
+    attr_accessor :client_version
+
+    # @return [String] The url of the client library being used
+    attr_accessor :client_url
+
+    # @return [Integer] The time, in seconds, in between each sync to the server. Defaults to +300+.
+    attr_accessor :polling_delay
+
+    # @return [Logger] Where to log messages. Must respond to same interface as Logger.
+    attr_reader :logger
+
+    # @return the middleware stack, if any, which should respond to +use+
+    attr_accessor :middleware
+
+    # @return [String] the path to a root certificate file used to verify ssl sessions. Default's to the root certificate file for copy-tuner.com.
+    attr_accessor :ca_file
+
+    # @return [Cache] instance used internally to synchronize changes.
+    attr_accessor :cache
+
+    # @return [Client] instance used to communicate with a CopyTuner Server.
+    attr_accessor :client
+
+    alias_method :secure?, :secure
+
+    # Instantiated from {CopyTunerClient.configure}. Sets defaults.
+    def initialize
+      self.client_name = 'CopyTuner Client'
+      self.client_url = 'https://rubygems.org/gems/copy_tuner_client'
+      self.client_version = VERSION
+      self.development_environments = %w(development staging)
+      self.host = 'copy-tuner.com'
+      self.http_open_timeout = 2
+      self.http_read_timeout = 5
+      self.logger = Logger.new($stdout)
+      self.polling_delay = 300
+      self.secure = false
+      self.test_environments = %w(test cucumber)
+      @applied = false
+    end
+
+    # Allows config options to be read like a hash
+    #
+    # @param [Symbol] option Key for a given attribute
+    # @return [Object] the given attribute
+    def [](option)
+      send(option)
+    end
+
+    # Returns a hash of all configurable options
+    # @return [Hash] configuration attributes
+    def to_hash
+      base_options = { :public => public? }
+
+      OPTIONS.inject(base_options) do |hash, option|
+        hash.merge option.to_sym => send(option)
+      end
+    end
+
+    # Returns a hash of all configurable options merged with +hash+
+    #
+    # @param [Hash] hash A set of configuration options that will take precedence over the defaults
+    # @return [Hash] the merged configuration hash
+    def merge(hash)
+      to_hash.merge hash
+    end
+
+    # Determines if the published or draft content will be used
+    # @return [Boolean] Returns +false+ if in a development or test
+    # environment, +true+ otherwise.
+    def public?
+      !(development_environments + test_environments).include?(environment_name)
+    end
+
+    # Determines if the content will be editable
+    # @return [Boolean] Returns +true+ if in a development environment, +false+ otherwise.
+    def development?
+      development_environments.include? environment_name
+    end
+
+    # Determines if the content will fetched from the server
+    # @return [Boolean] Returns +true+ if in a test environment, +false+ otherwise.
+    def test?
+      test_environments.include? environment_name
+    end
+
+    # Determines if the configuration has been applied (internal)
+    # @return [Boolean] Returns +true+ if applied, +false+ otherwise.
+    def applied?
+      @applied
+    end
+
+    # Applies the configuration (internal).
+    #
+    # Called automatically when {CopyTunerClient.configure} is called in the application.
+    #
+    # This creates the {I18nBackend} and puts them together.
+    #
+    # When {#test?} returns +false+, the poller will be started.
+    def apply
+      self.client ||= Client.new(to_hash)
+      self.cache ||= Cache.new(client, to_hash)
+      poller = Poller.new(cache, to_hash)
+      process_guard = ProcessGuard.new(cache, poller, to_hash)
+      I18n.backend = I18nBackend.new(cache)
+
+      if middleware && development?
+        middleware.use RequestSync, :cache => cache
+      end
+
+      @applied = true
+      logger.info "Client #{VERSION} ready"
+      logger.info "Environment Info: #{environment_info}"
+
+      unless test?
+        process_guard.start
+      end
+    end
+
+    def port
+      @port || default_port
+    end
+
+    # The protocol that should be used when generating URLs to CopyTuner.
+    # @return [String] +https+ if {#secure?} returns +true+, +http+ otherwise.
+    def protocol
+      if secure?
+        'https'
+      else
+        'http'
+      end
+    end
+
+    # For logging/debugging (internal).
+    # @return [String] a description of the environment in which this configuration was built.
+    def environment_info
+      parts = ["Ruby: #{RUBY_VERSION}", framework, "Env: #{environment_name}"]
+      parts.compact.map { |part| "[#{part}]" }.join(" ")
+    end
+
+    # Wraps the given logger in a PrefixedLogger. This way, CopyTunerClient
+    # log messages are recognizable.
+    # @param original_logger [Logger] the upstream logger to use, which must respond to the standard +Logger+ severity methods.
+    def logger=(original_logger)
+      @logger = PrefixedLogger.new("** [CopyTuner]", original_logger)
+    end
+
+    private
+
+    def default_port
+      if secure?
+        443
+      else
+        80
+      end
+    end
+  end
+end

data/lib/copy_tuner_client/errors.rb

@@ -0,0 +1,12 @@
+module CopyTunerClient
+  # Raised when an error occurs while contacting the CopyTuner server. This is
+  # raised by {Client} and generally rescued by {Cache}. The application will
+  # not encounter this error. Polling will continue even if this error is raised.
+  class ConnectionError < StandardError
+  end
+
+  # Raised when the client is configured with an api key that the CopyTuner
+  # server does not recognize. Polling is aborted when this error is raised.
+  class InvalidApiKey < StandardError
+  end
+end

data/lib/copy_tuner_client/i18n_backend.rb

@@ -0,0 +1,92 @@
+require 'i18n'
+
+module CopyTunerClient
+  # I18n implementation designed to synchronize with CopyTuner.
+  #
+  # Expects an object that acts like a Hash, responding to +[]+, +[]=+, and +keys+.
+  #
+  # This backend will be used as the default I18n backend when the client is
+  # configured, so you will not need to instantiate this class from the
+  # application. Instead, just use methods on the I18n class.
+  #
+  # This implementation will also load translations from locale files.
+  class I18nBackend
+    include I18n::Backend::Simple::Implementation
+
+    # Usually instantiated when {Configuration#apply} is invoked.
+    # @param cache [Cache] must act like a hash, returning and accept blurbs by key.
+    def initialize(cache)
+      @cache = cache
+    end
+
+    # Translates the given local and key. See the I18n API documentation for details.
+    #
+    # @return [Object] the translated key (usually a String)
+    def translate(locale, key, options = {})
+      content = super(locale, key, options.merge(:fallback => true))
+      if content.respond_to?(:html_safe)
+        content.html_safe
+      else
+        content
+      end
+    end
+
+    # Returns locales availabile for this CopyTuner project.
+    # @return [Array<String>] available locales
+    def available_locales
+      cached_locales = cache.keys.map { |key| key.split('.').first }
+      (cached_locales + super).uniq.map { |locale| locale.to_sym }
+    end
+
+    # Stores the given translations.
+    #
+    # Updates will be visible in the current process immediately, and will
+    # propagate to CopyTuner during the next flush.
+    #
+    # @param [String] locale the locale (ie "en") to store translations for
+    # @param [Hash] data nested key-value pairs to be added as blurbs
+    # @param [Hash] options unused part of the I18n API
+    def store_translations(locale, data, options = {})
+      super
+      store_item(locale, data)
+    end
+
+    private
+
+    def lookup(locale, key, scope = [], options = {})
+      parts = I18n.normalize_keys(locale, key, scope, options[:separator])
+      key_with_locale = parts.join('.')
+      content = cache[key_with_locale] || super
+      cache[key_with_locale] = "" if content.nil?
+      content
+    end
+
+    def store_item(locale, data, scope = [])
+      if data.respond_to?(:to_hash)
+        data.to_hash.each do |key, value|
+          store_item(locale, value, scope + [key])
+        end
+      elsif data.respond_to?(:to_str)
+        key = ([locale] + scope).join('.')
+        cache[key] = data.to_str
+      end
+    end
+
+    def load_translations(*filenames)
+      super
+      cache.wait_for_download
+    end
+
+    def default(locale, object, subject, options = {})
+      content = super(locale, object, subject, options)
+      if content.respond_to?(:to_str)
+        parts = I18n.normalize_keys(locale, object, options[:scope], options[:separator])
+        key = parts.join('.')
+        cache[key] = content.to_str
+      end
+      content
+    end
+
+    attr_reader :cache
+  end
+end