multilocale 0.1.0

data/lib/multilocale/client.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Multilocale
+  # HTTP client for the Multilocale REST API (https://api.multilocale.com).
+  #
+  #   client = Multilocale::Client.new(api_key: ENV["MULTILOCALE_API_KEY"])
+  #   client.projects.list
+  #   client.dictionary(project: "website", language: "es")
+  #
+  # Authentication is `Authorization: Basic base64(secret)` — the API key
+  # secret on its own, base64'd, with no key/secret pair and no colon. The
+  # secret selects both the organization and the project, so there is no
+  # tenant parameter to pass and no way for a key to reach another project.
+  class Client
+    DEFAULT_API_URL = "https://api.multilocale.com"
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 2
+    DEFAULT_RETRY_BACKOFF = 0.5
+
+    # 429 and 5xx are the transient ones. 4xx is the caller's problem and
+    # retrying it only burns rate limit.
+    RETRIABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+    RETRIABLE_EXCEPTIONS = [
+      Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
+      Errno::EHOSTUNREACH,
+      EOFError,
+      IOError,
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+      SocketError
+    ].freeze
+
+    attr_reader :api_url, :project, :open_timeout, :read_timeout, :max_retries, :retry_backoff, :user_agent
+
+    # @param api_key [String] REST API key secret, from app.multilocale.com → API keys
+    # @param access_token [String] operator session token, the alternative the
+    #   dashboard and the npm CLI use (`Authorization: Token base64(token)`).
+    #   Prefer an API key for anything automated: it is scoped and revocable.
+    # @param project [String] default project id or name for calls that take one
+    def initialize(
+      api_key: ENV.fetch("MULTILOCALE_API_KEY", nil),
+      access_token: ENV.fetch("MULTILOCALE_ACCESS_TOKEN", nil),
+      api_url: ENV.fetch("MULTILOCALE_API_URL", DEFAULT_API_URL),
+      project: ENV.fetch("MULTILOCALE_PROJECT", nil),
+      open_timeout: DEFAULT_OPEN_TIMEOUT,
+      read_timeout: DEFAULT_READ_TIMEOUT,
+      max_retries: DEFAULT_MAX_RETRIES,
+      retry_backoff: DEFAULT_RETRY_BACKOFF,
+      user_agent: nil,
+      logger: nil
+    )
+      api_key = nil if api_key.nil? || api_key.to_s.strip.empty?
+      access_token = nil if access_token.nil? || access_token.to_s.strip.empty?
+
+      if api_key.nil? && access_token.nil?
+        raise ConfigurationError, <<~MESSAGE
+          No Multilocale credential.
+
+          Create an API key at https://app.multilocale.com/keys and export it:
+
+            export MULTILOCALE_API_KEY=<the key secret>
+
+          or pass one explicitly: Multilocale::Client.new(api_key: "…").
+        MESSAGE
+      end
+
+      @api_key = api_key
+      @access_token = access_token
+      @api_url = api_url.to_s.sub(%r{/+\z}, "")
+      @project = project
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @max_retries = max_retries
+      @retry_backoff = retry_backoff
+      @user_agent = user_agent || "multilocale-ruby/#{VERSION} (ruby #{RUBY_VERSION})"
+      @logger = logger
+    end
+
+    def projects
+      @projects ||= Projects.new(self)
+    end
+
+    def phrases
+      @phrases ||= Phrases.new(self)
+    end
+
+    # One language of one project as a flat key => value dictionary.
+    #
+    # `project:` falls back to the client's own when it is nil, rather than
+    # defaulting in the signature: callers forward an optional value here, and
+    # `project: nil` would otherwise silently defeat the default.
+    def dictionary(language:, project: nil)
+      Dictionary.new(
+        language,
+        phrases.list(project: project_name(project || @project), language: language)
+          .each_with_object({}) { |phrase, entries| entries[phrase.key] = phrase.value }
+      )
+    end
+
+    # Every language of one project, as { "en" => Dictionary, … }.
+    def dictionaries(project: nil, languages: nil)
+      rows = phrases.list(project: project_name(project || @project))
+      dictionaries = Dictionary.from_phrases(rows)
+      return dictionaries if languages.nil?
+
+      languages.each_with_object({}) do |language, selected|
+        selected[language] = dictionaries[language] || Dictionary.new(language, {})
+      end
+    end
+
+    # Accepts an id, a name or a Project and returns the name the phrases
+    # endpoints filter on — they match `projects` (names), never ids.
+    def project_name(project_or_id)
+      raise ConfigurationError, "No project given, and no default project on the client." if project_or_id.nil?
+      return project_or_id.name if project_or_id.is_a?(Project)
+      return project_or_id unless project_or_id.to_s.match?(/\A[0-9a-f]{24}\z/)
+
+      projects.find(project_or_id).name
+    end
+
+    def get(path, params: nil)
+      request(:get, path, params: params)
+    end
+
+    def post(path, body:)
+      request(:post, path, body: body)
+    end
+
+    def put(path, body:)
+      request(:put, path, body: body)
+    end
+
+    def delete(path, params: nil)
+      request(:delete, path, params: params)
+    end
+
+    def request(method, path, params: nil, body: nil)
+      url = build_url(path, params)
+      uri = URI.parse(url)
+      attempt = 0
+
+      loop do
+        attempt += 1
+
+        begin
+          response = execute(method, uri, body)
+        rescue *RETRIABLE_EXCEPTIONS => error
+          raise ConnectionError, "#{method.to_s.upcase} #{url} failed: #{error.class}: #{error.message}" if attempt > max_retries
+
+          sleep(backoff_for(attempt))
+          next
+        end
+
+        status = response.code.to_i
+
+        if RETRIABLE_STATUSES.include?(status) && attempt <= max_retries
+          sleep(retry_after(response) || backoff_for(attempt))
+          next
+        end
+
+        return parse(response, method: method, url: url)
+      end
+    end
+
+    # Never let a credential reach a log line, an exception report or `p client`.
+    def inspect
+      "#<Multilocale::Client api_url=#{@api_url.inspect} auth=#{@api_key ? 'api_key' : 'access_token'} [redacted]>"
+    end
+    alias to_s inspect
+
+    private
+
+    def authorization
+      return "Basic #{Encoding.base64(@api_key)}" if @api_key
+
+      "Token #{Encoding.base64(@access_token)}"
+    end
+
+    def build_url(path, params)
+      url = "#{api_url}/api/#{path.to_s.sub(%r{\A/+}, '')}"
+      query = params && Encoding.query(params)
+      query && !query.empty? ? "#{url}?#{query}" : url
+    end
+
+    def execute(method, uri, body)
+      request = request_class(method).new(uri)
+      request["Accept"] = "application/json"
+      request["Authorization"] = authorization
+      request["User-Agent"] = user_agent
+
+      unless body.nil?
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+      end
+
+      @logger&.debug("multilocale #{method.to_s.upcase} #{uri}")
+
+      Net::HTTP.start(
+        uri.hostname,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: open_timeout,
+        read_timeout: read_timeout
+      ) { |http| http.request(request) }
+    end
+
+    def request_class(method)
+      case method
+      when :get then Net::HTTP::Get
+      when :post then Net::HTTP::Post
+      when :put then Net::HTTP::Put
+      when :delete then Net::HTTP::Delete
+      else raise ArgumentError, "Unsupported HTTP method #{method.inspect}"
+      end
+    end
+
+    def parse(response, method:, url:)
+      status = response.code.to_i
+      raw = response.body.to_s
+      payload =
+        begin
+          raw.empty? ? nil : JSON.parse(raw)
+        rescue JSON::ParserError
+          nil
+        end
+
+      return payload if status < 400
+
+      raise ApiError.build(
+        status: status,
+        payload: payload,
+        raw_body: raw,
+        request_method: method,
+        url: url
+      )
+    end
+
+    def retry_after(response)
+      seconds = response["Retry-After"]
+      return nil if seconds.nil?
+
+      value = seconds.to_f
+      value.positive? ? value : nil
+    end
+
+    def backoff_for(attempt)
+      retry_backoff * (2**(attempt - 1))
+    end
+  end
+end

data/lib/multilocale/config_file.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Multilocale
+  # multilocale.json — the same file the npm CLI reads, so a repository that
+  # uses both tools describes its project once.
+  #
+  #   {
+  #     "projectId": "website",
+  #     "defaultLocale": "en",
+  #     "locales": ["en", "es", "fr"],
+  #     "paths": ["config/locales/%lang%.yml"]
+  #   }
+  #
+  # `projectId` accepts an id or a name, exactly like the CLI's `--project`.
+  #
+  # Paths are resolved relative to the config file, not to the working
+  # directory: `rake` from a subdirectory writes the same files as `rake` from
+  # the root. (The npm CLI resolves them against the process cwd instead.)
+  class ConfigFile
+    FILENAME = "multilocale.json"
+
+    attr_reader :path, :data
+
+    def initialize(path, data)
+      @path = path
+      @data = data
+    end
+
+    # Walks up from `directory` looking for multilocale.json, the way git finds
+    # .git. Returns nil rather than raising: callers decide whether a missing
+    # config is fatal.
+    def self.discover(directory = Dir.pwd)
+      current = File.expand_path(directory)
+
+      loop do
+        candidate = File.join(current, FILENAME)
+        return load(candidate) if File.exist?(candidate)
+
+        parent = File.dirname(current)
+        return nil if parent == current
+
+        current = parent
+      end
+    end
+
+    def self.load(path)
+      raise ConfigurationError, "No such config file: #{path}" unless File.exist?(path)
+
+      data =
+        begin
+          JSON.parse(File.read(path))
+        rescue JSON::ParserError => error
+          raise ConfigurationError, "#{path} is not valid JSON: #{error.message}"
+        end
+
+      new(File.expand_path(path), data)
+    end
+
+    def directory
+      File.dirname(path)
+    end
+
+    # Id or name. Named `projectId` in the file for CLI compatibility even
+    # though a name is equally valid there.
+    def project
+      data["projectId"] || data["project"]
+    end
+
+    def default_locale
+      data["defaultLocale"]
+    end
+
+    def locales
+      data["locales"]
+    end
+
+    # The npm CLI's `import` and `unused` commands destructure this without a
+    # default and crash with "Cannot read properties of undefined" when it is
+    # missing; this gem answers with an empty list and lets the caller decide.
+    def paths
+      Array(data["paths"])
+    end
+
+    def format
+      data["format"]
+    end
+
+    def header
+      data["header"]
+    end
+
+    # Gem-only key. Absent from the CLI's vocabulary, which ignores unknown
+    # keys, so adding it here does not break `npx multilocale`.
+    def nested?
+      data.fetch("nested", true)
+    end
+
+    def project!
+      value = project
+      if value.nil? || value.to_s.empty?
+        raise ConfigurationError, <<~MESSAGE
+          #{path} does not say which project it describes.
+
+          Add the project id or name:
+
+            { "projectId": "website", "locales": ["en", "es"], "paths": ["config/locales/%lang%.yml"] }
+        MESSAGE
+      end
+
+      value
+    end
+
+    def paths!
+      values = paths
+      if values.empty?
+        raise ConfigurationError, <<~MESSAGE
+          #{path} has no "paths".
+
+          Add at least one path template containing #{LocaleFile::PLACEHOLDER}:
+
+            { "paths": ["config/locales/#{LocaleFile::PLACEHOLDER}.yml"] }
+        MESSAGE
+      end
+
+      values
+    end
+  end
+end

data/lib/multilocale/dictionary.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Multilocale
+  # One language's phrases as a flat `key => value` map, plus the conversion
+  # the Ruby i18n gem needs.
+  #
+  # Multilocale stores keys flat. The i18n gem resolves `t("cart.title")` by
+  # splitting on dots and walking nested hashes, so a flat YAML key
+  # `"cart.title": Cart` is NOT found at runtime — it has to be nested on the
+  # way out and flattened again on the way in. That translation is this class.
+  class Dictionary
+    include Enumerable
+
+    attr_reader :language, :entries
+
+    def initialize(language, entries = {})
+      @language = language
+      @entries = entries.sort_by { |key, _| key.to_s }.to_h
+    end
+
+    # { "en" => Dictionary, "es" => Dictionary, … } from a flat list of rows.
+    def self.from_phrases(phrases)
+      phrases.each_with_object({}) { |phrase, grouped|
+        (grouped[phrase.language] ||= {})[phrase.key] = phrase.value
+      }.map { |language, entries| [language, new(language, entries)] }.to_h
+    end
+
+    def [](key)
+      entries[key.to_s]
+    end
+
+    def each(&block)
+      entries.each(&block)
+    end
+
+    def size
+      entries.size
+    end
+
+    def empty?
+      entries.empty?
+    end
+
+    def keys
+      entries.keys
+    end
+
+    def to_h
+      entries
+    end
+
+    # Dotted keys become nested hashes, which is what i18n (and Rails) read.
+    # `cart.title` and `cart` cannot both be keys — one would have to be both a
+    # string and a hash — so that collision is reported rather than silently
+    # dropping one of them.
+    def nested
+      entries.each_with_object({}) do |(key, value), tree|
+        path = key.to_s.split(".")
+        leaf = path.pop
+        node = tree
+
+        path.each_with_index do |segment, index|
+          node[segment] ||= {}
+          unless node[segment].is_a?(Hash)
+            raise Error, "Key collision in #{language}: #{path[0..index].join('.')} is both a value and a namespace " \
+                         "(#{key})"
+          end
+
+          node = node[segment]
+        end
+
+        if node[leaf].is_a?(Hash)
+          raise Error, "Key collision in #{language}: #{key} is both a value and a namespace"
+        end
+
+        node[leaf] = value
+      end
+    end
+
+    # The inverse of #nested: what a locale file read from disk has to go
+    # through before it can be pushed back as phrase rows.
+    def self.flatten(tree, prefix = nil)
+      tree.each_with_object({}) do |(key, value), flat|
+        path = [prefix, key].compact.join(".")
+
+        if value.is_a?(Hash)
+          flat.merge!(flatten(value, path))
+        else
+          flat[path] = value
+        end
+      end
+    end
+  end
+end

data/lib/multilocale/encoding.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Multilocale
+  # Percent-encoding helpers written by hand on purpose: `base64` and `cgi` are
+  # bundled gems on modern Rubies, and this gem has zero runtime dependencies.
+  module Encoding
+    UNRESERVED = /[^A-Za-z0-9\-._~]/
+
+    module_function
+
+    # RFC 3986 unreserved-set encoding. Used for path segments (project names
+    # can contain spaces and slashes) and as the manual layer for phrase keys.
+    def percent_encode(value)
+      value.to_s.b.gsub(UNRESERVED) { |byte| format("%%%02X", byte.ord) }
+    end
+
+    # `Authorization: Basic <base64(secret)>` — one value, no colon, no
+    # newlines. `pack("m0")` is the dependency-free strict-Base64 encoder.
+    def base64(value)
+      [value.to_s].pack("m0")
+    end
+
+    # Phrase keys cross TWO decoders on the way in: Express decodes the query
+    # string, then the handler calls decodeURIComponent() on the result again
+    # (multilocale/api/handlers/phrasesHandler.js). A key is therefore
+    # documented as "URL-encoded" and must be encoded once here, on top of the
+    # transport's own encoding.
+    #
+    # It only matters for keys containing a literal '%' — 'discount.100%_off'
+    # arrives as 'discount.100' plus a decode error without this — but getting
+    # it wrong silently corrupts exactly the keys nobody thinks to test.
+    def phrase_key(key)
+      percent_encode(key)
+    end
+
+    # Query strings, with spaces as %20 rather than '+': the second decode a
+    # phrase key goes through is decodeURIComponent, which leaves '+' alone.
+    def query(params)
+      params
+        .reject { |_, value| value.nil? }
+        .map { |name, value| "#{percent_encode(name)}=#{percent_encode(value)}" }
+        .join("&")
+    end
+  end
+end

data/lib/multilocale/errors.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Multilocale
+  # Base class for everything this gem raises, so callers can rescue one thing.
+  class Error < StandardError; end
+
+  # Raised before any request is made: no credential, no project, a config file
+  # that does not say which project it describes.
+  class ConfigurationError < Error; end
+
+  # The request never got an HTTP response (DNS, TLS, timeout, reset) and the
+  # retry budget is spent.
+  class ConnectionError < Error; end
+
+  # The server answered with a status >= 400.
+  class ApiError < Error
+    attr_reader :status, :body, :request_method, :url
+
+    def initialize(message, status: nil, body: nil, request_method: nil, url: nil)
+      super(message)
+      @status = status
+      @body = body
+      @request_method = request_method
+      @url = url
+    end
+
+    STATUS_CLASSES = {
+      401 => "AuthenticationError",
+      403 => "PermissionError",
+      404 => "NotFoundError",
+      429 => "RateLimitedError"
+    }.freeze
+
+    # Maps an HTTP status onto the narrowest error class. 5xx is a single
+    # ServerError: the API returns the same `{status, message}` envelope for all
+    # of them and callers treat them identically (retry, then give up).
+    def self.class_for(status)
+      name = STATUS_CLASSES[status]
+      return Multilocale.const_get(name) if name
+      return ServerError if status >= 500
+
+      self
+    end
+
+    def self.build(status:, payload:, raw_body:, request_method:, url:)
+      message = payload.is_a?(Hash) ? payload["message"] : nil
+      message = "HTTP #{status}" if message.nil? || message.to_s.empty?
+
+      class_for(status).new(
+        "#{message} (#{request_method.to_s.upcase} #{url} -> #{status})#{hint_for(status)}",
+        status: status,
+        body: payload || raw_body,
+        request_method: request_method,
+        url: url
+      )
+    end
+
+    # The two failures every new integration hits, answered in the message
+    # itself rather than in a doc the reader is not looking at.
+    def self.hint_for(status)
+      case status
+      when 401
+        "\nCheck MULTILOCALE_API_KEY: the API expects Basic base64(secret) — the key secret alone, " \
+          "not key:secret."
+      when 403
+        "\nThe key is valid but not allowed here: a missing scope (projects:read, phrases:write, …) " \
+          "or a key scoped to a different project."
+      else
+        ""
+      end
+    end
+  end
+
+  class AuthenticationError < ApiError; end
+  class PermissionError < ApiError; end
+  class NotFoundError < ApiError; end
+  class RateLimitedError < ApiError; end
+  class ServerError < ApiError; end
+end