slang 0.34.0

data/lib/slang/snapshot/template.rb

@@ -0,0 +1,58 @@
+module Slang
+  class Snapshot
+    
+    # A template is an immutable object that contains a locale-specific (and possibly rule-specific) text string. It may
+    # contain interpolation variables, like {foo} or {bar}, that get replaced with values when interpolation is performed.
+    #
+    class Template
+
+      attr_reader :string
+
+      # Strict variable regex:
+      #   1. only lowercase letters (a-z), numerics (0-9), or underscores
+      #   2. minimum length 1, maximum length 63.
+      #
+      VARIABLE_NAME_REGEX = /\A[a-z0-9_]{1,63}\z/
+      VARIABLE_SCAN_REGEX = /\{([a-z0-9_]{1,63})\}/
+
+      # Create a template object. Scans the template for interpolation variables,
+      # and maintains a unique list. Assumes template variables are well-formed.
+      #
+      # @param [String] the base string for this template
+      #
+      def initialize(string)
+        @string = string.freeze
+        @interpolation_variables = string.scan(VARIABLE_SCAN_REGEX) # array of 1-element group arrays
+        @interpolation_variables.flatten!
+        @interpolation_variables.uniq!
+      end
+
+      # Performs variable substitutions on the template, returning a string. If there are any missing interpolation
+      # variables, the variable names are left uninterpolated in the string.
+      #
+      # @param [Hash{String => #to_s}] hash of variable names and their substitution values. Variable names should be
+      #   downcased strings at this point.
+      #
+      # @return [String] if successful, the interpolate string (frozen)
+      # @return [Array<(String,Array<String>)>] if missing variables, the string (frozen) without the missing variable
+      #   names interpolated, and an array of missing variable names.
+      #
+      def interpolate(variable_map)
+        return string if @interpolation_variables.empty?
+
+        missing_variables = []
+        s = string.dup
+        @interpolation_variables.each do |variable|
+          if variable_map.has_key?(variable) # explicitly check for key, thus allowing nil/false-y values
+            s.gsub!("{#{variable}}", variable_map[variable].to_s)
+          else
+            missing_variables << variable
+          end
+        end
+        s.freeze
+        missing_variables.empty? ? s : [ s, missing_variables ]
+      end
+
+    end # class
+  end
+end

data/lib/slang/snapshot/translation.rb

@@ -0,0 +1,135 @@
+require "slang/snapshot/rules"
+module Slang
+  class Snapshot
+
+    # A translation is an immutable object that references either a single template, or a group of templates that are
+    # selected via a rule pattern. For example, if the variable "count" is identified as a pluralization rule variable,
+    # its value will determine which pluralization template should be used. In English, the three templates would be:
+    # zero (count=0), one (count=1), and other (everything else).
+    #
+    class Translation
+      include Rules
+
+      # Strict key regex:
+      #   1. One or more dot separated components (namespaces).
+      #   2. Each component consists of lowercase a-z, numberics, or underscores.
+      #   3. Component length is 1-255.
+      #   4. Max number of components is 8
+      #   Thus, max key length is 2047.
+      #
+      KEY_REGEX = /\A[a-z0-9_]{1,255}(\.[a-z0-9_]{1,255}){0,7}\z/
+
+      attr_reader :key
+      attr_reader :rule_pattern
+      attr_reader :rules
+
+      # Create a Translation object from a translation array.
+      #
+      # @param [Array<(String,String,Array<String,Array<String>>)>] the translation array of the form: key name,
+      #   rules pattern, and an array whose elements are either all simple template Strings (if no rules), or all arrays
+      #   alternating between a rule selector String and a subtemplate String.
+      #
+      def initialize(translation_array)
+        @key, @rule_pattern, *@translations = translation_array
+        @rules = rules_from_pattern(@rule_pattern)
+        if @rules.nil?
+          Slang.log_warn("Ignoring key '#{@key}' because of unknown rule pattern '#{@rule_pattern}'")
+        elsif @rules.empty?
+          @translations.map! { |string| Template.new(string) unless string.empty? }
+        else
+          @translations.map! do |array|
+            subtemplates = {}
+            array.each_slice(2) do |selector, string|
+              subtemplates[selector] = Template.new(string) unless string.empty?
+            end
+            subtemplates
+          end
+        end
+        @key.freeze # avoid string duplication when added to hash
+      end
+
+      # Evaluate this translation given a locale and variable map. The returned array consists of a symbolic code for
+      # result (typically :success, but see below for error conditions), followed by the resulting String, and in error
+      # conditions, an array of variable names (see below).
+      #
+      # @param [Locale] a locale object
+      # @param [Hash{String => #to_s}] hash of variable names and their substitution values. Variable names should be
+      #   downcased strings at this point.
+      #
+      # @return [Array<(:success,String)]   successful evaluation with resulting string
+      # @return [Array<(:missing_template)] missing template error (no string result)
+      # @return [Array<(:missing_interpolation_variables,String,String,Array<String>)] missing interpolation variables,
+      #   string result, and array of missing interplotion variable names
+      # @return [Array<(:missing_rule_variables,String,Array<String>)] missing rule variables, string result, and
+      #   array of missing rule variable names.
+      # @return [Array<(:missing_rule_templates,String,Array<String>)] missing rule template, string result, and
+      #   array of attempted subtemplate selector names.
+      #
+      def evaluate(locale, variable_map)
+        result = template(locale, variable_map)
+        if result.first == :template
+          template, selector = result[1], result[2]
+          result = template.interpolate(variable_map)
+          if String === result
+            [ :success, result ]
+          else
+            string, missing_variable_names = *result
+            [ :missing_interpolation_variables, string, missing_variable_names, selector ]
+          end
+        else
+          result
+        end
+      end
+
+    private
+
+      # If a simple template, returns it. Otherwise evaluates rules with passed variables to determine which rule
+      # template should be used.
+      #
+      # @param [Locale] a locale object
+      # @param [Hash{String => #to_s}] hash of variable names and their substitution values. Variable names should be
+      #   downcased strings at this point.
+      #
+      # @return [Array<(:template,Template,String)>]                    if successful
+      # @return [Array<(:missing_rule_variables,String,Array<String>)>] if missing a required rule variable
+      # @return [Array<(:missing_template,String,Array<String>)>]       if missing subtemplate
+      #
+      def template(locale, variable_map)
+        t = @translations[locale.translation_index]
+        return [ :missing_template ] if t.nil?
+        return [ :template, t, nil ] if @rules.empty?
+
+        # evaluate rules with passed variables/values
+        missing_rule_variables = []
+        results = []
+        @rules.each do |variable, rule_type|
+          if variable_map.has_key?(variable) # explicitly check for key, thus allowing nil/false-y values
+            results << evaluate_rule(locale, rule_type, variable_map[variable])
+          else
+            missing_rule_variables << variable
+          end
+        end
+        if missing_rule_variables.any?
+          # {{en:key:<apples>,<bananas>}}
+          string = "{{#{locale.code}:#{@key}:#{missing_rule_variables.map { |v| "<#{v}>" }.join(",")}}}"
+          return [ :missing_rule_variables, string, missing_rule_variables ]
+        end
+
+        # +results+ is an array of arrays - each subarray contains the resulting value (or values) after applying
+        # the rule's logic. For example, in English pluralization, this could be ["zero","other"] if n = 0. In this
+        # case we would first attempt to find the "zero" template. If it doesn't exist, the "other" template would be
+        # used instead -- thus allowing translators to specify optional templates.
+
+        selectors = results.shift.product(*results).map { |values| values.join(":") }
+        selectors.each do |selector|
+          template = t[selector]
+          return [ :template, template, selector ] if template
+        end
+        # {{en:key:[zero],[other]}}
+        string = "{{#{locale.code}:#{@key}:#{selectors.map { |v| "[#{v}]" }.join(",")}}}"
+        [ :missing_rule_templates, string, selectors ]
+      end
+
+    end # class
+  end
+end

data/lib/slang/snapshot/warnings.rb

@@ -0,0 +1,102 @@
+module Slang
+  class Snapshot
+
+    # Warning logic, mixed in to Snapshot class.
+    #
+    module Warnings
+      attr_reader :warnings
+
+      def initialize
+        @warnings = {}
+        @warnings_lock = Monitor.new
+        super
+      end
+
+      # Warn unless warning_id already exists.
+      #
+      # @yieldreturn [Hash] warning hash detatils.
+      #
+      def warn(warning_id)
+        @warnings_lock.synchronize do
+          unless warnings.include?(warning_id)
+            warnings[warning_id] = yield
+          end
+        end
+      end
+
+      MISSING_KEY_WARNING = 1
+      MISSING_INTERPOLATION_VARIABLES_WARNING = 2
+      MISSING_RULE_VARIABLES_WARNING = 3
+      MISSING_RULE_TEMPLATES_WARNING = 4
+
+      # Record missing keys.
+      #
+      def missing_key!(locale, key, variable_map)
+        warning_id = "#{MISSING_KEY_WARNING}:#{locale.code}:#{key}"
+        warn(warning_id) do
+          Slang.log_warn("Missing key '#{key}' in locale '#{locale.code}'.")
+          {
+            warning:          MISSING_KEY_WARNING,
+            locale:           locale.code,
+            key:              key,
+            passed_variables: variable_map.keys,
+            timestamp:        Time.now.to_i
+          }
+        end
+      end
+
+      # Record missing interpolation variables.
+      #
+      def missing_interpolation_variables!(locale, key, selector, missing_variables, variable_map)
+        warning_id = "#{MISSING_INTERPOLATION_VARIABLES_WARNING}:#{locale.code}:#{key}:#{selector}:#{missing_variables.join(',')}"
+        warn(warning_id) do
+          Slang.log_warn("Key '#{key}' #{selector ? "(#{selector}) " : ''}in locale '#{locale.code}' missing interpolation variables: #{missing_variables.join(', ')} (passed: #{variable_map.inspect})")
+          {
+            warning:           MISSING_INTERPOLATION_VARIABLES_WARNING,
+            locale:            locale.code,
+            key:               key,
+            selector:          selector,
+            missing_variables: missing_variables,
+            passed_variables:  variable_map.keys,
+            timestamp:         Time.now.to_i
+          }
+        end
+      end
+
+      # Record missing rule variables.
+      #
+      def missing_rule_variables!(locale, key, missing_variables, variable_map)
+        warning_id = "#{MISSING_RULE_VARIABLES_WARNING}:#{locale.code}:#{key}:#{missing_variables.join(",")}"
+        warn(warning_id) do
+          Slang.log_warn("Key '#{key}' in locale '#{locale.code}' is missing required rule variables: #{missing_variables.join(', ')} (passed: #{variable_map.inspect})")
+          {
+            warning:           MISSING_RULE_VARIABLES_WARNING,
+            locale:            locale.code,
+            key:               key,
+            missing_variables: missing_variables,
+            passed_variables:  variable_map.keys,
+            timestamp:         Time.now.to_i
+          }
+        end
+      end
+
+      # Record missing selectors/templates.
+      #
+      def missing_rule_templates!(locale, key, missing_templates, variable_map)
+        warning_id = "#{MISSING_RULE_TEMPLATES_WARNING}:#{locale.code}:#{key}:#{missing_templates.join(',')}"
+        warn(warning_id) do
+          Slang.log_warn("Key '#{key}' in locale '#{locale.code}' is missing template selectors: #{missing_templates.join(', ')} (passed: #{variable_map.inspect})")
+          {
+            warning:           MISSING_RULE_TEMPLATES_WARNING,
+            locale:            locale.code,
+            key:               key,
+            missing_templates: missing_templates,
+            passed_variables:  variable_map.keys,
+            timestamp:         Time.now.to_i
+          }
+        end
+      end
+
+    end # module
+  end
+end

data/lib/slang/updater/abstract.rb

@@ -0,0 +1,74 @@
+require "slang/updater/http_helpers"
+module Slang
+  module Updater
+
+    class Abstract
+      include HTTPHelpers
+
+      attr_reader :uri
+      attr_reader :data_dir
+      attr_reader :shared_state
+      attr_reader :lock
+
+      def initialize(env, url, data_dir, embedded_path)
+        @env = env
+        @uri = URI(url)
+        @data_dir = File.expand_path(data_dir)
+        @shared_state = SharedState.new(data_file_path("state"))
+        @lock = Mutex.new
+
+        new_snapshot = nil
+        shared_state.exclusive_lock do |state|
+
+          # try cached first
+          if state[:snapshot_id]
+            path = data_file_path(state[:snapshot_id])
+            begin
+              new_snapshot = Snapshot.from_json(File.read(path))
+              Slang.log_info("Loaded cached snapshot.")
+            rescue => e
+              Slang.log_warn("Unable to load cached snapshot #{path} - #{e.message}")
+              FileUtils.rm(path, force: true)
+            end
+          end
+
+          unless new_snapshot
+            # then embedded
+            if embedded_path
+              begin
+                json = File.read(embedded_path)
+                new_snapshot = Snapshot.from_json(json)
+                Slang.log_info("Loaded embedded snapshot.")
+              rescue => e
+                Slang.log_warn("Unable to load embedded snapshot #{embedded_path} - #{e.message}")
+              end
+            end
+            unless new_snapshot
+              # then empty
+              json = Snapshot::EMPTY_SNAPSHOT_JSON
+              new_snapshot = Snapshot.from_json(json)
+              Slang.log_warn("Created an empty snapshot.")
+            end
+            File.write(data_file_path(new_snapshot.id), json)
+            state[:snapshot_id] = new_snapshot.id
+            if is_a?(Production)
+              state[:modified_at] = new_snapshot.timestamp
+              state[:check_at] = Time.now.to_f
+            end
+          end
+        end
+        activate(new_snapshot)
+      end
+
+      def data_file_path(filename)
+        File.join(data_dir, "#{@env}_#{filename}")
+      end
+
+      def activate(new_snapshot)
+        lock.synchronize { @snapshot = new_snapshot }
+        Slang.log_info("Activated snapshot - #{new_snapshot.id} (#{Time.at(new_snapshot.timestamp)}).")
+      end
+
+    end # class
+  end
+end

data/lib/slang/updater/development.rb

@@ -0,0 +1,88 @@
+require "slang/updater/abstract"
+require "slang/updater/squelchable"
+module Slang
+  module Updater
+
+    # Development-mode snapshot updater.
+    #
+    class Development < Abstract
+      include Squelchable
+
+      AUTO_CHECK = 60
+      RATE_LIMIT = 1
+
+      attr_accessor :dev_key
+
+      # Get the latest snapshot. Triggers a background update when accessed. Thread-safe.
+      #
+      # @return [Snapshot] the current snapshot.
+      #
+      def snapshot
+        pid = Process.pid
+        lock.synchronize do
+          unless @pid == pid
+            @pid = pid
+            @thread = Thread.new { loop { run_loop } }
+            Thread.new { loop { sleep(AUTO_CHECK + rand); @thread.wakeup } }
+            Slang.log_info("Started background update thread (pid=#{pid}).")
+          end
+          @thread.wakeup
+          @snapshot
+        end
+      end
+
+    private
+
+      def run_loop
+        unless squelched?
+          begin
+            check_for_snapshot
+            squelch!(RATE_LIMIT)
+          rescue NetworkError => e
+            squelch!(e.retry_in, "network failure - #{e.message}")
+          rescue => e
+            squelch!(nil, "unexpected error - #{e.message}")
+            Slang.log_error(e.backtrace.join("\n")) unless SlangError === e
+          end
+        end
+        Thread.stop # snapshot requests awaken this thread
+      end
+
+      def check_for_snapshot
+        Slang.log_debug("Checking for new snapshot...")
+        body = get_dev_snapshot
+        if body.nil?
+          Slang.log_debug("...not modified.")
+          return
+        end
+
+        new_snapshot = Snapshot.from_json(body)
+        if new_snapshot.id == @snapshot.id
+          Slang.log_debug("...same snapshot, no changes.")
+          return
+        end
+
+        File.write(data_file_path(new_snapshot.id), body)
+        shared_state.exclusive_lock { |state| state[:snapshot_id] = new_snapshot.id }
+        FileUtils.rm(data_file_path(@snapshot.id), force: true)
+
+        activate(new_snapshot) # last
+      end
+
+      def get_dev_snapshot
+        response = get(uri, "X-Slang-Dev-Key" => dev_key, "If-Modified-Since" => Time.at(@snapshot.timestamp).httpdate)
+        case response
+        when Net::HTTPNotModified # 304
+          nil
+        when Net::HTTPOK # 200
+          response.body
+        when Net::HTTPServerError # 5xx
+          raise NetworkError.new(TEMPORARY_RETRY), "Server error (#{response.code})."
+        else
+          raise NetworkError.new(nil), "Unexpected response (#{response.code})."
+        end
+      end
+
+    end # class
+  end
+end