haveapi 0.29.1 → 0.29.3

data/lib/haveapi/locales/en.yml

@@ -5,33 +5,57 @@
 en:
   haveapi:
     action_state:
-      cancellation_failed: cancellation failed
-      not_found: action state not found
-      timeout_max: timeout has to be maximally %{max}
+      cancellation_failed: Action cancellation failed
+      not_found: Action state not found
+      timeout_max: timeout must be at most %{max}
     authentication:
-      failed: authentication failed
-      invalid_credentials: invalid authentication credentials
-      multiple_oauth2_tokens: Multiple OAuth2 tokens provided
-      multiple_tokens: Multiple authentication tokens provided
-      renew_failed: renew failed
-      required: Action requires user to authenticate
-      revoke_failed: revoke failed
-      token_required: Action requires user to authenticate with a token
+      basic:
+        description: |-
+          Authentication using HTTP Basic. The username and password are passed in an HTTP header.
+          This method must not be used from web browsers.
+      failed: Authentication failed
+      invalid_credentials: Invalid authentication credentials
+      multiple_oauth2_tokens: Multiple OAuth2 tokens were provided
+      multiple_tokens: Multiple authentication tokens were provided
+      oauth2:
+        description: |-
+          OAuth2 authorization provider.
+          HaveAPI clients have limited OAuth2 support, but the API can be used as an authentication source and OAuth2 tokens can be used to access it. HaveAPI partially implements RFC 6749: authorization response type "code" and token grant types "authorization_code" and "refresh_token". Other response and grant types are not supported at this time. The access token can be passed as a bearer token according to RFC 6750, or using a custom HTTP header when the Authorization header is not practical.
+          Access and refresh tokens can be revoked according to RFC 7009.
+      renew_failed: Token renewal failed
+      required: This action requires authentication
+      revoke_failed: Token revocation failed
+      token:
+        actions:
+          renew:
+            description: Renew the current authentication token
+          request:
+            description: Request an authentication token
+          revoke:
+            description: Revoke the current authentication token
+        description: The client authenticates with credentials, usually a username
+          and password, and receives a token. From that point on, the credentials
+          can be forgotten and the token is used instead. Tokens can have different
+          lifetimes and can be renewed or revoked. The token is passed either in an
+          HTTP header or as a query parameter.
+        resource:
+          description: Manage authentication tokens
+      token_required: This action requires token authentication
     authorization:
       insufficient_permissions: Access denied. Insufficient permissions.
     errors:
       action_not_found: Action not found
-      bad_accept_header: Bad Accept header
-      bad_json_syntax: Bad JSON syntax
-      json_body_object: JSON body must be an object
-      server_error: Server error occurred
-      unsupported_content_type: Unsupported Content-Type
+      bad_accept_header: Invalid Accept header
+      bad_json_syntax: Invalid JSON syntax
+      json_body_object: The JSON request body must be an object
+      server_error: A server error occurred
+      unsupported_content_type: Unsupported Content-Type header
     pagination:
-      limit_max: limit has to be maximally %{max}
+      limit_max: limit must be at most %{max}
     parameters:
       action_state:
         can_cancel:
-          description: When true, execution of this action can be cancelled
+          description: When true, this action can be cancelled
           label: Can cancel
         created_at:
           label: Created at
@@ -43,60 +67,59 @@ en:
           label: Label
         poll:
           current:
-            description: progress to check with if update_in is set
+            description: Current progress value to compare when update_in is set
           status:
-            description: status to check with if update_in is set
+            description: Status value to compare when update_in is set
           timeout:
-            description: in seconds
+            description: Timeout in seconds
             label: Timeout
           total:
-            description: progress to check with if update_in is set
+            description: Total progress value to compare when update_in is set
           update_in:
-            description: number of seconds after which the state is returned if the
-              progress has changed
-            label: Progress
+            description: Return early when status, current, or total changes; the
+              value is passed to API-specific polling implementations
+            label: Update in
         status:
-          description: Determines whether the action is proceeding or failing
+          description: Whether the action is proceeding successfully or has failed
           label: Status
         total:
-          description: The action is finished when current equals to total
+          description: The action is finished when current reaches total
           label: Total
         unit:
           description: Unit of current and total
           label: Unit
         updated_at:
-          description: When was the progress last updated
+          description: When the progress was last updated
           label: Updated at
       action_state_id:
-        description: ID of ActionState object for state querying. When null, the action
-          is not blocking for the current invocation.
+        description: |-
+          ID of the ActionState object for state polling.
+          When null, the action is not blocking for the current invocation.
         label: Action state ID
       active_record:
         includes:
-          description: |-
-            A list of names of associated resources separated by a comma.
-            Nested associations are declared with '__' between resource names.
-            For example, 'user,node' will resolve the two associations.
-            To resolve further associations of node, use e.g. 'user,node__location',
-            to go even deeper, use e.g. 'user,node__location__environment'.
+          description: A comma-separated list of associated resource names. Nested
+            associations are declared with '__' between resource names. For example,
+            'user,node' includes these two associations. To include further associations
+            of node, use e.g. 'user,node__location'; to go even deeper, use e.g. 'user,node__location__environment'.
           label: Included associations
         path_params:
-          description: An array of parameters needed to resolve URL to this object
+          description: An array of parameters needed to build the URL for this object
           label: URL parameters
         resolved:
-          description: True if the association is resolved
+          description: True if the association has been loaded
           label: Resolved
       authentication:
         token:
           interval:
-            description: How long will requested token be valid, in seconds.
+            description: How long the requested token will be valid, in seconds.
             label: Interval
           lifetime:
             description: |-
-              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
+              fixed - the token has a fixed validity period and cannot be renewed
+              renewable_manual - the token can be renewed, but only manually using the renew action
+              renewable_auto - the token is renewed automatically to now + interval whenever it is used
+              permanent - the token is valid forever unless deleted
             label: Lifetime
           password:
             label: Password
@@ -106,39 +129,52 @@ en:
             label: User
       default:
         count:
-          label: Return the count of all items
+          label: Return total count
         total_count:
-          label: Total count of all items
+          label: Total item count
       metadata:
         'no':
           label: Disable metadata
       paginable:
         from_id:
-          description: List objects with greater/lesser ID
+          description: List objects with IDs greater or lower than this value
           label: From ID
         limit:
           description: Number of objects to retrieve
           label: Limit
+    resources:
+      action_state:
+        actions:
+          cancel:
+            description: Cancel a pending action
+          index:
+            description: List pending action states
+          poll:
+            description: Return when the action is completed, its progress changes,
+              or a timeout occurs
+          show:
+            description: Show the state of a pending action
+        description: Browse states of blocking actions
     types:
-      invalid_boolean: not a valid boolean %{value}
-      invalid_datetime: not in ISO 8601 format '%{value}'
-      invalid_float: not a valid float %{value}
-      invalid_integer: not a valid integer %{value}
-      invalid_string: not a valid string %{value}
+      invalid_boolean: 'not a valid boolean: %{value}'
+      invalid_datetime: 'not in ISO 8601 format: ''%{value}'''
+      invalid_float: 'not a valid float: %{value}'
+      invalid_integer: 'not a valid integer: %{value}'
+      invalid_string: 'not a valid string: %{value}'
     validation:
       cannot_be_null: cannot be null
       includes_only_strings: includes must contain only strings
       includes_string_or_array: includes must be a string or array
-      input_parameters_not_valid: input parameters not valid
-      invalid_id: not a valid id %{value}
+      input_parameters_not_valid: input parameters are not valid
+      invalid_id: 'not a valid ID: %{value}'
       invalid_input_layout: invalid input layout
       invalid_path_parameter_encoding: invalid path parameter encoding
       invalid_string_encoding: invalid string encoding
-      required_parameter_missing: required parameter missing
+      required_parameter_missing: required parameter is missing
       resource_not_found: resource not found
     validators:
       acceptance:
-        accepted: has to be %{value}
+        accepted: must be %{value}
       confirmation:
         different: must be different from %{parameter}
         same: must be the same as %{parameter}
@@ -149,20 +185,20 @@ en:
       inclusion:
         included: "%{value} cannot be used"
       length:
-        equals: length has to be %{equals}
-        max: length has to be maximally %{max}
-        min: length has to be minimally %{min}
-        range: length has to be in range <%{min}, %{max}>
+        equals: length must be %{equals}
+        max: length must be at most %{max}
+        min: length must be at least %{min}
+        range: length must be between %{min} and %{max}
       numericality:
         composite: "%{requirements}"
-        even: even
-        max: has to be maximally %{max}
-        min: has to be minimally %{min}
-        mod: mod %{mod} must equal zero
-        number: has to be a number
-        odd: odd
-        range: has to be in range <%{min}, %{max}>
-        step: in steps of %{step}
+        even: must be even
+        max: must be at most %{max}
+        min: must be at least %{min}
+        mod: remainder after division by %{mod} must be zero
+        number: must be a number
+        odd: must be odd
+        range: must be between %{min} and %{max}
+        step: must be in steps of %{step}
       presence:
         non_empty: must be present and non-empty
         present: must be present

data/lib/haveapi/parameters/metadata_i18n.rb

@@ -14,7 +14,7 @@ module HaveAPI::Parameters
           keys:,
           value:
         }
-      end
+      end + choice_i18n_catalog_items(context, i18n_path)
     end
 
     private
@@ -27,6 +27,17 @@ module HaveAPI::Parameters
       localized_metadata(context, i18n_path, :description, @desc)
     end
 
+    def localized_validators(context, i18n_path, validators)
+      include_validator = validators[:include]
+      return validators unless include_validator && include_validator.has_key?(:values)
+
+      values = include_validator.fetch(:values)
+      localized_values = localized_choice_values(context, i18n_path, values)
+      return validators if localized_values.equal?(values)
+
+      validators.merge(include: include_validator.merge(values: localized_values))
+    end
+
     def localized_metadata(context, i18n_path, kind, fallback)
       keys = metadata_i18n_keys(context, i18n_path, kind, fallback)
       default = HaveAPI.localize(fallback)
@@ -61,6 +72,74 @@ module HaveAPI::Parameters
       [exact_key, *metadata_i18n_default_keys(context, i18n_path, kind, scope)].uniq
     end
 
+    def localized_choice_values(context, i18n_path, values)
+      case values
+      when ::Hash
+        values.to_h do |value, label|
+          [
+            value,
+            localized_metadata(context, i18n_path, choice_i18n_kind(value), label)
+          ]
+        end
+      when ::Array
+        localized = values.to_h do |value|
+          label = localized_metadata(
+            context,
+            i18n_path,
+            choice_i18n_kind(value),
+            value.to_s
+          )
+          [value, label]
+        end
+
+        localized.any? { |value, label| label.to_s != value.to_s } ? localized : values
+      else
+        values
+      end
+    end
+
+    def choice_i18n_catalog_items(context, i18n_path)
+      values = choice_i18n_values
+      return [] unless values
+
+      choice_i18n_fallbacks(values).filter_map do |value, fallback|
+        keys = metadata_i18n_keys(context, i18n_path, choice_i18n_kind(value), fallback)
+        label = HaveAPI.localize(fallback).to_s.strip
+
+        next if keys.empty? || label.empty?
+
+        {
+          param: HaveAPI::Params.i18n_segment(@name),
+          kind: metadata_i18n_key_suffix(choice_i18n_kind(value)),
+          keys:,
+          value: label
+        }
+      end
+    end
+
+    def choice_i18n_values
+      metadata_i18n_choice_values
+    end
+
+    def metadata_i18n_choice_values
+      nil
+    end
+
+    def choice_i18n_fallbacks(values)
+      case values
+      when ::Hash
+        values
+      when ::Array
+        values.to_h { |value| [value, value.to_s] }
+      else
+        {}
+      end
+    end
+
+    def choice_i18n_kind(value)
+      "choices.#{HaveAPI::Params.i18n_segment(value)}.label"
+    end
+
     def metadata_i18n_fallback(kind)
       case kind
       when :label
@@ -78,8 +157,6 @@ module HaveAPI::Parameters
         @label_key
       when :description
         @desc_key
-      else
-        raise ArgumentError, "unsupported parameter metadata kind #{kind.inspect}"
       end
     end
 

data/lib/haveapi/parameters/typed.rb

@@ -62,7 +62,7 @@ module HaveAPI::Parameters
         label: localized_label(context, i18n_path),
         description: localized_description(context, i18n_path),
         type: @type ? @type.to_s : String.to_s,
-        validators: @validators ? @validators.describe : {},
+        validators: @validators ? localized_validators(context, i18n_path, @validators.describe) : {},
         default: @default,
         protected: @protected || false
       }
@@ -167,6 +167,10 @@ module HaveAPI::Parameters
       @type == Custom
     end
 
+    def metadata_i18n_choice_values
+      @validators&.describe&.dig(:include, :values)
+    end
+
     def normalize_custom_keys(value)
       case value
       when ::Hash

data/lib/haveapi/resources/action_state.rb

@@ -2,7 +2,7 @@ require 'haveapi/resource'
 
 module HaveAPI::Resources
   class ActionState < HaveAPI::Resource
-    desc 'Browse states of blocking actions'
+    desc HaveAPI.message('haveapi.resources.action_state.description')
     auth false
     version :all
 
@@ -54,7 +54,7 @@ module HaveAPI::Resources
     class Index < HaveAPI::Actions::Default::Index
       include Mixin
 
-      desc 'List states of pending actions'
+      desc HaveAPI.message('haveapi.resources.action_state.actions.index.description')
 
       input(:hash) do
         string :order, choices: %w[newest oldest], default: 'newest', fill: true
@@ -85,7 +85,7 @@ module HaveAPI::Resources
 
       MAX_TIMEOUT = 30
 
-      desc 'Returns when the action is completed or timeout occurs'
+      desc HaveAPI.message('haveapi.resources.action_state.actions.poll.description')
       http_method :get
       route '{%{resource}_id}/poll'
 
@@ -157,7 +157,7 @@ module HaveAPI::Resources
     class Show < HaveAPI::Actions::Default::Show
       include Mixin
 
-      desc 'Show state of a pending action'
+      desc HaveAPI.message('haveapi.resources.action_state.actions.show.description')
 
       output(:hash) do
         use :all
@@ -178,6 +178,8 @@ module HaveAPI::Resources
     end
 
     class Cancel < HaveAPI::Action
+      desc HaveAPI.message('haveapi.resources.action_state.actions.cancel.description')
+
       http_method :post
       route '{%{resource}_id}/cancel'
       blocking true

data/lib/haveapi/version.rb

@@ -1,4 +1,4 @@
 module HaveAPI
   PROTOCOL_VERSION = '2.0'.freeze
-  VERSION = '0.29.1'.freeze
+  VERSION = '0.29.3'.freeze
 end

data/spec/action/runtime_spec.rb

@@ -638,7 +638,7 @@ describe HaveAPI::Action do
 
       expect(last_response.status).to eq(200)
       expect(api_response).not_to be_ok
-      expect(api_response.errors[:confirmed]).to include('required parameter missing')
+      expect(api_response.errors[:confirmed]).to include('required parameter is missing')
 
       call_api([:Test], :batch, { tests: [{ label: 'one' }], _meta: { confirmed: 'maybe' } })
 

data/spec/action/validation_http_status_spec.rb

@@ -33,7 +33,7 @@ describe HaveAPI::Action do
 
         expect(last_response.status).to eq(200)
         expect(api_response).not_to be_ok
-        expect(api_response.errors[:name]).to include('required parameter missing')
+        expect(api_response.errors[:name]).to include('required parameter is missing')
       end
     end
 
@@ -69,7 +69,7 @@ describe HaveAPI::Action do
 
         expect(last_response.status).to eq(400)
         expect(api_response).not_to be_ok
-        expect(api_response.errors[:name]).to include('required parameter missing')
+        expect(api_response.errors[:name]).to include('required parameter is missing')
       end
     end
   end

data/spec/action_state_spec.rb

@@ -184,7 +184,7 @@ describe HaveAPI::Resources::ActionState do
       get_action '/v1/action_states/999'
 
       expect(api_response).not_to be_ok
-      expect(api_response.message).to eq('action state not found')
+      expect(api_response.message).to eq('Action state not found')
     end
 
     it 'poll returns immediately if finished' do
@@ -227,7 +227,7 @@ describe HaveAPI::Resources::ActionState do
 
       expect(last_response.status).to eq(200)
       expect(api_response).not_to be_ok
-      expect(api_response.errors[:timeout].first).to include('range <0, 30>')
+      expect(api_response.errors[:timeout].first).to include('between 0 and 30')
     end
 
     it 'poll returns immediately when update_in check mismatches' do
@@ -274,7 +274,7 @@ describe HaveAPI::Resources::ActionState do
       get_action '/v1/action_states/999/poll', action_state: { timeout: 0 }
 
       expect(api_response).not_to be_ok
-      expect(api_response.message).to eq('action state not found')
+      expect(api_response.message).to eq('Action state not found')
     end
 
     it 'cancel returns ok for true' do
@@ -303,7 +303,7 @@ describe HaveAPI::Resources::ActionState do
       call_api(:post, '/v1/action_states/1/cancel', {})
 
       expect(api_response).not_to be_ok
-      expect(api_response.message).to eq('cancellation failed')
+      expect(api_response.message).to eq('Action cancellation failed')
     end
 
     it 'cancel returns error for NotImplementedError' do

data/spec/authentication/basic_spec.rb

@@ -73,7 +73,7 @@ describe HaveAPI::Authentication::Basic::Provider do
     expect(last_response.headers['www-authenticate']).to include('Basic realm=')
 
     expect(api_response).to be_failed
-    expect(api_response.message).to include('authenticate')
+    expect(api_response.message).to eq('This action requires authentication')
     expect(seen_users.last).to be_nil
   end
 
@@ -123,7 +123,7 @@ describe HaveAPI::Authentication::Basic::Provider do
     expect(last_response.status).to eq(401)
     expect(last_response.headers['www-authenticate']).to include('Basic realm=')
     expect(api_response).to be_failed
-    expect(api_response.message).to include('authenticate')
+    expect(api_response.message).to eq('This action requires authentication')
   end
 
   it 'returns an authentication error envelope from _logout' do
@@ -132,6 +132,6 @@ describe HaveAPI::Authentication::Basic::Provider do
     expect(last_response.status).to eq(401)
     expect(last_response.headers['www-authenticate']).to include('Basic realm=')
     expect(api_response).to be_failed
-    expect(api_response.message).to include('authenticate')
+    expect(api_response.message).to eq('This action requires authentication')
   end
 end

data/spec/authentication/oauth2_spec.rb

@@ -225,7 +225,7 @@ describe HaveAPI::Authentication::OAuth2 do
 
       expect(last_response.status).to eq(400)
       expect(api_response).to be_failed
-      expect(api_response.message).to eq('Bylo poskytnuto více OAuth2 tokenů')
+      expect(api_response.message).to eq('Bylo zadáno více OAuth2 tokenů')
     end
 
     it 'ignores structured access_token query values before backend lookup' do
@@ -248,6 +248,7 @@ describe HaveAPI::Authentication::OAuth2 do
     end
 
     it 'exposes oauth2 provider in version description' do
+      header 'Accept-Language', 'cs'
       call_api(:options, '/v1/')
 
       expect(last_response.status).to eq(200)
@@ -257,6 +258,7 @@ describe HaveAPI::Authentication::OAuth2 do
       expect(auth).to have_key(:oauth2)
 
       desc = auth[:oauth2]
+      expect(desc[:description]).to start_with('OAuth2 autorizační provider')
       expect(desc).to have_key(:http_header)
       expect(desc[:http_header]).to eq('X-HaveAPI-OAuth2-Token')
 

data/spec/authentication/token_spec.rb

@@ -290,6 +290,7 @@ describe HaveAPI::Authentication::Token do
   end
 
   it 'exposes token provider in version description' do
+    header 'Accept-Language', 'cs'
     call_api(:options, '/v1/')
 
     expect(last_response.status).to eq(200)
@@ -297,11 +298,18 @@ describe HaveAPI::Authentication::Token do
 
     auth = api_response[:authentication]
     expect(auth).to have_key(:token)
+    expect(auth[:token][:description]).to start_with('Klient se autentizuje')
     expect(auth[:token][:http_header]).to eq(AuthSpecToken::Config.http_header)
     expect(auth[:token][:query_parameter]).to eq(AuthSpecToken::Config.query_parameter.to_s)
 
     expect(auth[:token]).to have_key(:resources)
     expect(auth[:token][:resources]).to have_key(:token)
+
+    resource = auth[:token][:resources][:token]
+    expect(resource[:description]).to eq('Spravovat autentizační tokeny')
+    expect(resource[:actions][:request][:description]).to eq('Vyžádat autentizační token')
+    expect(resource[:actions][:revoke][:description]).to eq('Zneplatnit aktuální autentizační token')
+    expect(resource[:actions][:renew][:description]).to eq('Obnovit aktuální autentizační token')
   end
 end
 

data/spec/extensions/exception_mailer_spec.rb

@@ -113,7 +113,7 @@ describe HaveAPI::Extensions::ExceptionMailer do
 
     expect(last_response.status).to eq(500)
     expect(api_response).not_to be_ok
-    expect(api_response.message).to eq('Server error occurred')
+    expect(api_response.message).to eq('A server error occurred')
 
     expect(calls.size).to eq(1)
     context, exception, body = calls.first
@@ -190,6 +190,6 @@ describe HaveAPI::Extensions::ExceptionMailer do
 
     expect(last_response.status).to eq(500)
     expect(api_response).not_to be_ok
-    expect(api_response.message).to eq('Server error occurred')
+    expect(api_response.message).to eq('A server error occurred')
   end
 end