haveapi 0.28.4 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12a166f4b2cfae2e1046011ec072c2d3cfe2bae2c6e22aa7ccbb8a3a772fc4cd
-  data.tar.gz: 919fcc67646a1c52b1410500a74e27b3628403e97f97c095523d78bef4046210
+  metadata.gz: b5fea26ee9dde153cf44881ba46fe548ebe63077029d787e9b8e82ac19295d27
+  data.tar.gz: 9314173d105633354963d996f0d8f4ceb70d5ec30c22684ced53052d694d9463
 SHA512:
-  metadata.gz: 8f818bba5c50921fa6dc188345aabed20988fa499af2de594ad3f44af0614bd0ffe94aec7a13558bc72492f46b2fb1ce6c92b24d7a53af5be964e056d0a1a2fa
-  data.tar.gz: 38095fce8f5b1abfa3d630f5188bbed4d1203ea5ce70ec2f8a2f59faab16c1edfb863441a77a87cd1a5155e623331e32a45e434f163d3ed03cb4c3ac3cb77a79
+  metadata.gz: 6b1fb3f7ea1140e86091161f740399c258540036c5dccd04e2c9c6c632d0ef8f5e9cd4ab3cf9ecfec7f2952f109b50716fd255bb22fd385efea4c2ea47df6999
+  data.tar.gz: e68a162dc87376dccfc8b5db1cc190aae4e1a47ff18029f21325b7dc2dc063aa522af594cedf0bec2a2f7d0c00d1df4f75151405a83e32821f7289ad4a14775b

data/README.md

@@ -224,6 +224,145 @@ This should start the application using WEBrick. Check
 
 and more.
 
+## Localization
+
+HaveAPI can translate framework-owned response messages, validation errors and
+validator descriptions using Ruby `i18n`. The JSON envelope shape does not
+change; `message`, `errors` and self-description validator messages are still
+plain strings. Existing application-supplied strings passed to `error!` or
+custom validator `message:` options are returned unchanged.
+
+English is the default locale. Czech translations are bundled and can be
+selected with `Accept-Language: cs` or a regional tag such as
+`Accept-Language: cs-CZ`.
+
+```ruby
+api = HaveAPI::Server.new(MyAPI)
+
+api.default_locale = :en
+api.available_locales = %i[en cs]
+api.locale_header = 'Accept-Language'
+
+api.locale do |request:, current_user:, default_locale:|
+  current_user&.language&.code || default_locale
+end
+```
+
+The explicit request header has precedence over the resolver. The resolver is
+called again after authentication, so applications can use authenticated user
+preferences when the client did not request a locale. If `locale_header` is set
+to a custom header name, HaveAPI also allows that header in CORS preflight
+responses. The header value uses the same syntax as `Accept-Language`.
+
+Actions can opt into application translations by passing lazy messages to
+`error!` or validator options:
+
+```ruby
+error!(api_message('my_api.errors.quota_exceeded', limit: max_limit))
+
+input do
+  string :name, required: {
+    message: HaveAPI.message('my_api.validation.name_required')
+  }
+end
+```
+
+Use `api_t(key, **values)` when an immediate string translation is needed in an
+action. Use `HaveAPI.message(key, **values)` in class-level DSL blocks such as
+`input`.
+
+Action parameter labels and descriptions can be translated from the
+self-description context. Set `parameter_i18n_scope` to an application locale
+namespace and keep the existing English labels/descriptions as fallbacks:
+
+```ruby
+api.parameter_i18n_scope = 'my_api'
+
+input do
+  string :hostname,
+         label: 'Hostname',
+         desc: 'VPS hostname'
+end
+```
+
+HaveAPI first looks up the exact action parameter key:
+
+```yaml
+cs:
+  my_api:
+    resources:
+      vps:
+        actions:
+          create:
+            input:
+              hostname:
+                label: "Hostname"
+                description: "Nazev VPS"
+```
+
+The generated path is
+`resources.<resource_path>.actions.<action>.<input|output>.<name>`.
+Metadata parameters include the metadata type and direction, for example
+`resources.vps.actions.create.meta.global.output.action_state_id.label`.
+
+If the exact key is missing, HaveAPI falls back to resource input/output keys,
+resource attributes and then shared attributes:
+
+```yaml
+cs:
+  my_api:
+    resources:
+      vps:
+        input:
+          hostname:
+            label: "Hostname"
+            description: "Nazev VPS"
+        output:
+          hostname:
+            label: "Hostname"
+        attributes:
+          hostname:
+            label: "Hostname"
+    attributes:
+      hostname:
+        label: "Hostname"
+```
+
+Metadata parameters fall back through resource and global metadata keys:
+
+```yaml
+cs:
+  my_api:
+    resources:
+      vps:
+        meta:
+          global:
+            output:
+              count:
+                label: "Return item count"
+    meta:
+      global:
+        output:
+          count:
+            label: "Return item count"
+```
+
+Framework-owned HaveAPI metadata, such as pagination and built-in meta
+parameters, is translated by HaveAPI itself and is not looked up in the
+application parameter scope. Use `label_key` and `desc_key` when a parameter
+needs an explicit key that is not derived from its action location:
+
+```ruby
+string :hostname,
+       label: 'Hostname',
+       desc: 'VPS hostname',
+       label_key: 'my_api.attributes.hostname.label',
+       desc_key: 'my_api.attributes.hostname.description'
+```
+
+HaveAPI also exposes `api.parameter_metadata_i18n_items` for maintenance tools
+that generate application locale catalogs from declared parameters.
+
 ### Run with rackup
 Use the same code as above, only the last line would be
 

data/Rakefile

@@ -3,6 +3,7 @@ require 'rspec/core'
 require 'rspec/core/rake_task'
 require 'active_support/core_ext/string/inflections'
 require 'haveapi'
+require 'haveapi/tasks/i18n'
 require 'haveapi/tasks/yard'
 
 RSpec::Core::RakeTask.new(:spec) do |spec|

data/haveapi.gemspec

@@ -15,7 +15,8 @@ Gem::Specification.new do |s|
   s.required_ruby_version = ">= #{File.read('../../.ruby-version').strip}"
 
   s.add_dependency 'activesupport', '>= 7.1'
-  s.add_dependency 'haveapi-client', '~> 0.28.4'
+  s.add_dependency 'haveapi-client', '~> 0.29.0'
+  s.add_dependency 'i18n', '>= 1.6', '< 2'
   s.add_dependency 'json'
   s.add_dependency 'mail'
   s.add_dependency 'nesty', '~> 1.0'

data/lib/haveapi/action.rb

@@ -109,9 +109,8 @@ module HaveAPI
           meta(:global) do
             output do
               integer :action_state_id,
-                      label: 'Action state ID',
-                      desc: 'ID of ActionState object for state querying. When null, the action ' \
-                            'is not blocking for the current invocation.'
+                      label: HaveAPI.message('haveapi.parameters.action_state_id.label'),
+                      desc: HaveAPI.message('haveapi.parameters.action_state_id.description')
             end
           end
         end
@@ -231,12 +230,12 @@ module HaveAPI
 
         {
           auth: @auth,
-          description: @desc,
+          description: HaveAPI.localize(@desc),
           aliases: @aliases,
           blocking: @blocking ? true : false,
           input: @input ? @input.describe(context) : { parameters: {} },
           output: @output ? @output.describe(context) : { parameters: {} },
-          meta: @meta ? @meta.merge(@meta) { |_, v| v && v.describe(context) } : nil,
+          meta: @meta ? @meta.to_h { |type, v| [type, v && v.describe(context, type:)] } : nil,
           examples: @examples ? @examples.describe(context) : [],
           scope: context.action_scope,
           path: context.resolved_path,
@@ -245,6 +244,16 @@ module HaveAPI
         }
       end
 
+      def parameter_metadata_i18n_items(context)
+        [
+          *@input&.parameter_metadata_i18n_items(context),
+          *@output&.parameter_metadata_i18n_items(context),
+          *(@meta&.flat_map do |type, metadata|
+            metadata&.parameter_metadata_i18n_items(context, type:)
+          end)
+        ].compact
+      end
+
       # Inherit attributes from resource action is defined in.
       def inherit_attrs_from_resource(action, r, attrs)
         begin
@@ -339,7 +348,7 @@ module HaveAPI
       status = @context.server.validation_error_http_status
       opts[:http_status] = status if status
 
-      error!(e.message, e.to_hash, opts)
+      error!(e.message_value, e.to_hash, opts)
     end
 
     def authorized?(user)
@@ -397,7 +406,7 @@ module HaveAPI
         if tmp.empty?
           p e.message
           puts e.backtrace
-          error!('Server error occurred', {}, http_status: 500)
+          error!(HaveAPI.message('haveapi.errors.server_error'), {}, http_status: 500)
         end
 
         unless tmp[:status]
@@ -415,7 +424,7 @@ module HaveAPI
 
         return [
           tmp[:status] || false,
-          tmp[:message] || 'Server error occurred',
+          tmp[:message] || HaveAPI.message('haveapi.errors.server_error'),
           {},
           tmp[:http_status] || 500
         ]
@@ -507,7 +516,7 @@ module HaveAPI
     output {}
     meta(:global) do
       input do
-        bool :no, label: 'Disable metadata'
+        bool :no, label: HaveAPI.message('haveapi.parameters.metadata.no.label')
       end
     end
 
@@ -592,6 +601,14 @@ module HaveAPI
       throw(:return, false)
     end
 
+    def api_message(...)
+      HaveAPI.message(...)
+    end
+
+    def api_t(...)
+      HaveAPI.t(...)
+    end
+
     private
 
     def validate

data/lib/haveapi/actions/default.rb

@@ -11,11 +11,14 @@ module HaveAPI
 
         meta(:global) do
           input do
-            bool :count, label: 'Return the count of all items', default: false
+            bool :count,
+                 label: HaveAPI.message('haveapi.parameters.default.count.label'),
+                 default: false
           end
 
           output do
-            integer :total_count, label: 'Total count of all items'
+            integer :total_count,
+                    label: HaveAPI.message('haveapi.parameters.default.total_count.label')
           end
         end
 

data/lib/haveapi/actions/paginable.rb

@@ -4,10 +4,14 @@ module HaveAPI::Actions
 
     def self.included(action)
       action.input do
-        integer :from_id, label: 'From ID', desc: 'List objects with greater/lesser ID',
-                          number: { min: 0 }
-        integer :limit, label: 'Limit', desc: 'Number of objects to retrieve',
-                        number: { min: 0, max: MAX_LIMIT }
+        integer :from_id,
+                label: HaveAPI.message('haveapi.parameters.paginable.from_id.label'),
+                desc: HaveAPI.message('haveapi.parameters.paginable.from_id.description'),
+                number: { min: 0 }
+        integer :limit,
+                label: HaveAPI.message('haveapi.parameters.paginable.limit.label'),
+                desc: HaveAPI.message('haveapi.parameters.paginable.limit.description'),
+                number: { min: 0, max: MAX_LIMIT }
       end
     end
   end

data/lib/haveapi/authentication/oauth2/provider.rb

@@ -127,7 +127,7 @@ module HaveAPI::Authentication
             tokens.first
           else
             raise HaveAPI::Authentication::TokenConflict,
-                  'Multiple OAuth2 tokens provided'
+                  HaveAPI.t('haveapi.authentication.multiple_oauth2_tokens')
           end
 
         token && config.find_user_by_access_token(request, token)

data/lib/haveapi/authentication/token/config.rb

@@ -75,9 +75,16 @@ module HaveAPI::Authentication
           # Default request
           subclass.request do
             input do
-              string :user, label: 'User', required: true
-              password :password, label: 'Password', required: true
-              string :scope, label: 'Scope', default: 'all', fill: true
+              string :user,
+                     label: HaveAPI.message('haveapi.parameters.authentication.token.user.label'),
+                     required: true
+              password :password,
+                       label: HaveAPI.message('haveapi.parameters.authentication.token.password.label'),
+                       required: true
+              string :scope,
+                     label: HaveAPI.message('haveapi.parameters.authentication.token.scope.label'),
+                     default: 'all',
+                     fill: true
             end
 
             handle do

data/lib/haveapi/authentication/token/provider.rb

@@ -177,7 +177,7 @@ module HaveAPI::Authentication
           tokens.first
         else
           raise HaveAPI::Authentication::TokenConflict,
-                'Multiple authentication tokens provided'
+                HaveAPI.t('haveapi.authentication.multiple_tokens')
         end
       end
 
@@ -217,18 +217,17 @@ module HaveAPI::Authentication
                 instance_exec(&block)
               end
 
-              string :lifetime, label: 'Lifetime', required: true,
-                                choices: %i[fixed renewable_manual renewable_auto permanent],
-                                desc: <<~END
-                                  fixed - the token has a fixed validity period, it cannot be renewed
-                                  renewable_manual - the token can be renewed, but it must be done manually via renew action
-                                  renewable_auto - the token is renewed automatically to now+interval every time it is used
-                                  permanent - the token will be valid forever, unless deleted
-                                END
-              integer :interval, label: 'Interval',
-                                 desc: 'How long will requested token be valid, in seconds.',
-                                 default: 60 * 5, fill: true,
-                                 number: { min: 1, max: 86_400 }
+              string :lifetime,
+                     label: HaveAPI.message('haveapi.parameters.authentication.token.lifetime.label'),
+                     required: true,
+                     choices: %i[fixed renewable_manual renewable_auto permanent],
+                     desc: HaveAPI.message('haveapi.parameters.authentication.token.lifetime.description')
+              integer :interval,
+                      label: HaveAPI.message('haveapi.parameters.authentication.token.interval.label'),
+                      desc: HaveAPI.message('haveapi.parameters.authentication.token.interval.description'),
+                      default: 60 * 5,
+                      fill: true,
+                      number: { min: 1, max: 86_400 }
             end
 
             output(:hash) do
@@ -245,7 +244,7 @@ module HaveAPI::Authentication
             def validate!
               validate
             rescue HaveAPI::ValidationError => e
-              error!(e.message, e.to_hash, http_status: 400)
+              error!(e.message_value, e.to_hash, http_status: 400)
             end
 
             def exec
@@ -261,7 +260,9 @@ module HaveAPI::Authentication
               end
 
               unless result.ok?
-                error!(result.error || 'invalid authentication credentials')
+                error!(
+                  result.error || HaveAPI.message('haveapi.authentication.invalid_credentials')
+                )
               end
 
               {
@@ -292,7 +293,7 @@ module HaveAPI::Authentication
 
               unless user
                 error!(
-                  'Action requires user to authenticate with a token',
+                  HaveAPI.message('haveapi.authentication.token_required'),
                   {},
                   http_status: 401
                 )
@@ -311,7 +312,7 @@ module HaveAPI::Authentication
               if result.ok?
                 ok!
               else
-                error!(result.error || 'revoke failed')
+                error!(result.error || HaveAPI.message('haveapi.authentication.revoke_failed'))
               end
             end
           end
@@ -339,7 +340,7 @@ module HaveAPI::Authentication
 
               unless user
                 error!(
-                  'Action requires user to authenticate with a token',
+                  HaveAPI.message('haveapi.authentication.token_required'),
                   {},
                   http_status: 401
                 )
@@ -358,7 +359,7 @@ module HaveAPI::Authentication
               if result.ok?
                 { valid_to: result.valid_to }
               else
-                error!(result.error || 'renew failed')
+                error!(result.error || HaveAPI.message('haveapi.authentication.renew_failed'))
               end
             end
           end
@@ -387,7 +388,7 @@ module HaveAPI::Authentication
               def validate!
                 validate
               rescue HaveAPI::ValidationError => e
-                error!(e.message, e.to_hash, http_status: 400)
+                error!(e.message_value, e.to_hash, http_status: 400)
               end
 
               define_method(:exec) do
@@ -402,7 +403,7 @@ module HaveAPI::Authentication
                 end
 
                 unless result.ok?
-                  error!(result.error || 'authentication failed')
+                  error!(result.error || HaveAPI.message('haveapi.authentication.failed'))
                 end
 
                 {

data/lib/haveapi/context.rb

@@ -113,7 +113,10 @@ module HaveAPI
 
     def resolve_arg!(path, arg)
       value = arg.to_s
-      raise HaveAPI::ValidationError, 'invalid path parameter encoding' unless value.valid_encoding?
+      unless value.valid_encoding?
+        raise HaveAPI::ValidationError,
+              HaveAPI.message('haveapi.validation.invalid_path_parameter_encoding')
+      end
 
       path.sub!(/\{[a-zA-Z0-9\-_]+\}/, value)
     end

data/lib/haveapi/i18n.rb

@@ -0,0 +1,125 @@
+require 'i18n'
+
+module HaveAPI
+  class LocalizedMessage
+    attr_reader :key, :values, :default
+
+    def initialize(key, default: nil, scope: nil, **values)
+      @key = normalize_key(key, scope)
+      @default = default
+      @values = values
+    end
+
+    def translate(extra_values = {})
+      values = localized_values(@values.merge(extra_values))
+      opts = values
+      opts[:default] = @default if @default
+
+      ::I18n.t(@key, **opts)
+    end
+
+    def to_s
+      translate
+    end
+
+    private
+
+    def normalize_key(key, scope)
+      return key.to_s unless scope
+
+      "#{scope}.#{key}"
+    end
+
+    def localized_values(values)
+      values.transform_values do |value|
+        case value
+        when Array
+          value.map { |v| HaveAPI.localize(v) }.join('; ')
+        else
+          HaveAPI.localize(value)
+        end
+      end
+    end
+  end
+
+  module I18n
+    class << self
+      def setup
+        locale_dir = File.expand_path('locales', __dir__)
+        ::I18n.load_path |= Dir[File.join(locale_dir, '*.yml')]
+      end
+
+      def available_locales
+        locale_dir = File.expand_path('locales', __dir__)
+
+        Dir[File.join(locale_dir, '*.yml')].map do |path|
+          File.basename(path, '.yml').to_sym
+        end.sort
+      end
+
+      def accept_language(header, available_locales)
+        header.to_s.split(',').each_with_index.filter_map do |raw, index|
+          tag, *params = raw.strip.split(';')
+          next if tag.nil? || tag.empty?
+
+          q = params.map(&:strip).grep(/\Aq=/).first
+          weight = q ? q.split('=', 2).last.to_f : 1.0
+          next if weight <= 0.0
+
+          [tag, weight, index]
+        end.sort_by { |(_, weight, index)| [-weight, index] }.each do |tag, _, _|
+          locale = normalize_locale(tag, available_locales)
+          return locale if locale
+        end
+
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def normalize_locale(locale, available_locales)
+        return if locale.nil?
+
+        tag = locale.to_s.strip.tr('_', '-')
+        return if tag.empty? || tag == '*'
+
+        available = Array(available_locales).map(&:to_s)
+        candidates = [tag, tag.split('-').first].compact.map(&:downcase).uniq
+
+        candidates.each do |candidate|
+          match = available.detect { |v| v.downcase == candidate }
+          return match.to_sym if match
+        end
+
+        nil
+      end
+    end
+  end
+
+  class << self
+    def message(key, default: nil, scope: nil, **values)
+      LocalizedMessage.new(key, default:, scope:, **values)
+    end
+
+    def t(key, default: nil, scope: nil, **values)
+      message(key, default:, scope:, **values).translate
+    end
+
+    def localize(value, **extra_values)
+      case value
+      when LocalizedMessage
+        value.translate(extra_values)
+      when Array
+        value.map { |v| localize(v, **extra_values) }
+      when Hash
+        value.transform_values { |v| localize(v, **extra_values) }
+      when String
+        extra_values.empty? ? value : format(value, extra_values)
+      else
+        value
+      end
+    end
+  end
+end
+
+HaveAPI::I18n.setup