haveapi 0.32.1 → 0.32.2

data/doc/{documentation-ui.md → en/documentation-ui.md}

@@ -86,9 +86,33 @@ Version-specific navigation puts Authentication before Resources and indents
 authentication methods beneath it. Technical references are linked under
 HaveAPI internals in the versions-index sidebar, and retain their direct URLs.
 
+## Documentation language
+
+Open **Documentation settings** and use **Language**, above **Theme**, to select
+**English** or **Česky**. Before a choice is saved, the documentation follows the
+browser's weighted `Accept-Language` preferences, including regional tags such
+as `cs-CZ` and `en-GB`, and falls back to English. Detecting a language does not
+save it. Changing the select saves the choice and reloads the current page,
+preserving its path, query and fragment.
+
+A valid `doc_lang=en` or `doc_lang=cs` query takes precedence over the saved
+`haveapi.docs.locale` cookie, then browser preferences, then English. The cookie
+is host-only, scoped to the API mount, uses SameSite=Lax, and is Secure on HTTPS.
+If cookies are unavailable, the query still selects the language for that page,
+but the choice cannot persist through the cookie. With JavaScript, only the
+select is shown. Without JavaScript, use the submit button after choosing a
+language; native form submission does not preserve the fragment.
+Search uses the page's effective documentation language without saving a choice.
+
+The API reference and HaveAPI internal articles share this setting. Articles
+without a Czech translation show the English source with a notice. Article
+links and existing section fragments retain their public URLs. Documentation
+language does not change API action requests, OPTIONS responses, account
+language or the API's request-locale configuration.
+
 ## Themes and examples
 
-The sidebar controls theme, language, client variant and example detail for
+The sidebar controls theme, programming language, client variant and example detail for
 all examples on the page. Open **Documentation settings** and use the **Theme**
 controls to select **Automatic**, **Light** or **Dark**. Automatic follows the
 operating system. The versions index and shared internal pages use the same
@@ -99,10 +123,10 @@ client, authenticated when required. **With error handling** demonstrates
 additional error checks or diagnostics. Initialization and authentication
 examples remain on their respective pages.
 
-Choose a language first. The Client selector appears when that language has
-multiple variants, such as Callback and Async. Examples stays visible and shows
-the choices supported by the selected client on the current page. A selector
-with only one choice is disabled.
+Choose a programming language first (labeled **Jazyk** in Czech). The Client selector appears when that language has
+multiple variants, such as Callback and Async. The Examples selector appears
+when the selected client supports more than one detail level on the current
+page. If only one level is available, examples use it automatically.
 
 A client can offer only Simple on an initialization page and both levels on an
 action page. Each example uses With error handling only when that group supports
@@ -114,7 +138,19 @@ Use the copy icon inside a code block's top-right corner to copy its displayed c
 If the browser cannot copy it, select the code and copy it manually. Copying an
 example does not change the selected language, detail or scroll position.
 
-The browser stores these choices in `haveapi.docs.preferences.v1`. Preference
+Without JavaScript, choose a programming language and press **Apply**. The page
+reloads with that language's client variants. Choose the variant and example
+detail, then press **Apply** again. The selected example opens in each group;
+other examples stay available in their disclosure panels. These GET submissions
+retain the current page, search query and explicit documentation language, and
+may drop the fragment. They do not save example preferences. With JavaScript,
+changes apply immediately and the Apply button is hidden. Explicit example
+choices in a URL take precedence over saved choices for that page without
+saving them on load.
+
+The browser stores theme, programming language, client variant and example detail
+in `haveapi.docs.preferences.v1`; its `language` field selects the programming
+language. The documentation language uses its separate cookie. Preference
 data contains no credentials or API responses. Choices are checked against the
 clients available in the current API; an unavailable saved client uses an
 available fallback.

data/doc/{performance.md → en/performance.md}

@@ -291,6 +291,17 @@ This rule permits coordinated package-version changes without changing baseline
 selection or the separate historical 0.30 maintenance-lineage proof. Response
 changes remain diagnostics under the existing per-revision stability policy.
 
+Ordinary `source_versions` capture also normalizes one reviewed server-gemspec
+packaging change: the exact shallow `doc/*` file-list assignment and its exact
+recursive `doc/**/*` form with `File.file?` filtering. Only one matching
+assignment is accepted; unknown or duplicate statements retain their strict
+bytes. The receipt records `file_selection: documentation-files-v1`, preserves
+raw contents and hashes, and is reconstructed during replay. Removing or changing
+the marker fails validation. Legacy receipts still use their original raw
+file-selection rule. All other gemspec bytes, evaluated dependencies and Ruby
+requirements, runtime and lock inputs remain strict. The historical maintenance
+comparison does not use this packaging normalization.
+
 ## GitHub workflow and baseline selection
 
 The `servers/ruby performance` workflow runs on pushes, ordinary pull requests,

data/doc/{protocol.md → en/protocol.md}

@@ -67,8 +67,8 @@ be encoded in any of the supported output formats.
 
 ## API version
 
-<a href="/doc/protocol.png">
-<img src="/doc/protocol.png"
+<a href="../protocol.png">
+<img src="../protocol.png"
      alt="Diagram representing the structure of an API version"
 	 width="600">
 </a>

data/doc/en/readme.md

@@ -0,0 +1,423 @@
+# HaveAPI
+Server-side implementation of the [HaveAPI](https://github.com/vpsfreecz/haveapi)
+protocol in Ruby in the form of a framework that can be used to create
+self-descriptive RESTful web APIs. The framework features a DSL aimed at
+creating API resources, actions and specifying input/output parameters. HaveAPI
+handles everything from HTTP communication, authentication, parsing of input
+parameters and formatting output, so that users can focus on their bussiness
+logic.
+
+## Server framework features
+- Handles network communication, authentication, authorization, input/output formats
+  and parameters, you need only to define resources and actions
+- By writing the code you get the documentation for free
+- Auto-generated online HTML documentation
+- ORM integration
+  - ActiveRecord
+    - integrated with controller
+    - loads and documents validators from models
+    - eager loading
+  - easy to support other ORM frameworks
+
+## Usage
+This text might not be complete or up-to-date, as things still often change.
+Full use of HaveAPI may be seen
+in [vpsadmin-api](https://github.com/vpsfreecz/vpsadmin-api)
+([online doc](https://api.vpsfree.cz)), which may serve as an example of how
+are things meant to be used.
+
+All resources and actions are represented by classes. They all must be stored
+in a module, whose name is later given to HaveAPI. HaveAPI then searches all
+classes in this module and builds your API.
+
+For the purposes of this document, all resources will be in module `MyAPI`.
+
+### Example
+This is a basic example, it does not show all options and functions.
+
+Let's assume a model:
+
+```ruby
+class User < ActiveRecord::Base
+  validates :login, :full_name, :role, presence: true
+  validates :login, format: {
+      with: /[a-zA-Z\.\-]{3,30}/,
+      message: 'not a valid login'
+  }, uniqueness: true
+  validates :role, inclusion: {
+    in: %w(admin user),
+    message '%{value} is not a valid role'
+  }
+
+  # An example authentication with plain text password
+  def self.authenticate(username, password)
+    u = User.find_by(login: username)
+
+    if u
+      u if u.password == password
+    end
+  end
+end
+```
+
+Resource user might look like this:
+```ruby
+module MyAPI
+  class User < HaveAPI::Resource
+    # This resource belongs to version 1.
+    # It is also possible to put resource to multiple versions, e.g. [1, 2]
+    version 1
+
+    # Provide description for this resource
+    desc 'Manage users'
+
+    # ActiveRecord model to load validators from
+    model ::User
+
+    # Require authentication, this is the default
+    auth true
+
+    # Create a named group of shared params, that may be later included
+    # by actions.
+    params(:id) do
+      id :id, label: 'User ID'
+    end
+
+    params(:common) do
+      string :login, label: 'Login', desc: 'Used for authentication'
+      string :full_name, label: 'Full name'
+      string :role, label: 'User role', desc: 'admin or user'
+    end
+
+    # Actions
+    # Module HaveAPI::Actions::Default contains helper classes that define
+    # HTTP methods and routes for generic actions.
+    class Index < HaveAPI::Actions::Default::Index
+      desc 'List all users'
+
+      # There are no input parameters
+
+      # Output parameters
+      output(:object_list) do
+        use :id
+        use :common
+      end
+
+      # Determine if current user can use this action.
+      # allow/deny immediately returns from this block.
+      # Default rule is deny.
+      authorize do |u|
+        allow if u.role == 'admin'
+        deny  # deny is implicit, so it may be omitted
+      end
+
+      # Provide example usage
+      example do
+        request({})
+        response({
+          users: [
+            {
+              id: 1,
+              login: 'myuser',
+              full_name: 'My Very Name'
+            }
+          ]
+        })
+        comment 'Get a list of all users like this'
+      end
+
+      # Helper method returning a query for all users
+      def query
+        ::User.all
+      end
+
+      # This method is called if the request has meta[:count] = true
+      def count
+        query.count
+      end
+
+      # Execute action, return the list
+      def exec
+        with_pagination(query)
+      end
+    end
+
+    class Create < HaveAPI::Actions::Default::Create
+      desc 'Create new user'
+
+      input do
+        use :common
+      end
+
+      output do
+        use :id
+        use :common
+      end
+
+      authorize do |u|
+        allow if u.role == 'admin'
+        deny
+      end
+
+      example do
+        request({
+          user: {
+            login: 'anotherlogin',
+            full_name: 'My Very New Name'
+          }
+        })
+        response({
+          user: {
+            id: 2
+          }
+        })
+        comment 'Create new user like this'
+      end
+
+      def exec
+        user = ::User.new(input)
+
+        if user.save
+          ok!(user)
+        else
+          error!('save failed', user.errors.to_hash)
+        end
+      end
+    end
+  end
+end
+```
+
+### What you get
+From this piece of code, HaveAPI will generate a self-describing API.
+It will contain resource `User` with actions `Index` and `Create`,
+using which you can list existing users and create new ones.
+
+You can use any of the available clients to work with the API.
+
+### Run the example
+```ruby
+api = HaveAPI::Server.new(MyAPI)
+
+# Use HTTP basic auth
+class BasicAuth < HaveAPI::Authentication::Basic::Provider
+  def find_user(request, username, password)
+      User.authenticate(username, password)
+  end
+end
+
+api.use_version(:all)
+api.auth_chain << BasicAuth
+api.mount('/')
+
+api.start!
+```
+
+This should start the application using WEBrick. Check
+[http://localhost:4567](http://localhost:4567).
+
+- `GET /` - a list of API versions
+- `GET /doc` - HaveAPI documentation
+- `GET /v1/` - documentation for version 1
+- `OPTIONS /` - description for the whole API
+- `OPTIONS /v1/` - description for API version 1
+
+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"
+```
+
+Choice labels declared through the `choices`/`include` validator use the same
+parameter metadata path with `choices.<value>.label` appended. If choices were
+declared as a value-to-label map, the declared label is used as the English
+fallback. If choices were declared as an array, untranslated self-description
+keeps the array form; a locale that supplies labels is returned as the existing
+HaveAPI `{value: label}` map form.
+
+```yaml
+cs:
+  my_api:
+    resources:
+      vps:
+        attributes:
+          state:
+            choices:
+              running:
+                label: "bezi"
+              stopped:
+                label: "vypnuto"
+```
+
+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
+
+```ruby
+run api.app
+```
+
+## Authentication
+HaveAPI defines an interface for creating authentication providers.
+HTTP basic auth and token providers are built-in.
+
+Authentication options are self-described. A client can choose what authentication
+method it understands and wants to use.
+
+## Authorization
+HaveAPI provides means for authorizing user access to actions. This process
+is not self-described.
+
+If the user is authenticated when requesting self-description, only allowed
+resources, actions and parameters will be returned.
+
+## Validation of input data
+Because validators are a part of the API's documentation, the clients can
+perform client-side validation before the data is sent to the API server.
+
+## Blocking actions
+Blocking mode is for actions whose execution is not immediate but takes an unspecified
+amount of time. HaveAPI protocol allows clients to monitor progress of such actions
+or cancel their execution.
+
+## Contributing
+
+1. Fork it ( https://github.com/vpsfreecz/haveapi/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/haveapi.gemspec

@@ -9,13 +9,13 @@ Gem::Specification.new do |s|
     s.description = 'Framework for creating self-describing APIs'
   s.authors     = 'Jakub Skokan'
   s.email       = 'jakub.skokan@vpsfree.cz'
-  s.files       = `git ls-files -z`.split("\x0") + Dir.glob('doc/*')
+  s.files       = `git ls-files -z`.split("\x0") + Dir.glob('doc/**/*').select { |path| File.file?(path) }
   s.license     = 'MIT'
 
   s.required_ruby_version = ">= #{File.read('../../.ruby-version').strip}"
 
   s.add_dependency 'activesupport', '>= 7.1'
-  s.add_dependency 'haveapi-client', '~> 0.32.1'
+  s.add_dependency 'haveapi-client', '~> 0.32.2'
   s.add_dependency 'i18n', '>= 1.6', '< 2'
   s.add_dependency 'json'
   s.add_dependency 'mail'

data/lib/haveapi/client_example.rb

@@ -171,6 +171,19 @@ module HaveAPI
       context&.detail == :thorough
     end
 
+    def example_comment(key, default:, **values)
+      if context.respond_to?(:example_comment)
+        context.example_comment(key, default:, **values)
+      else
+        values.empty? ? default : format(default, values)
+      end
+    end
+
+    # Prefix every physical prose line before combining it with executable source.
+    def comment_lines(text, prefix)
+      text.gsub(/\r\n?/, "\n").split("\n", -1).map { |line| "#{prefix}#{line}" }.join("\n")
+    end
+
     def version_url
       File.join(base_url, "v#{version}", '/')
     end
@@ -194,7 +207,7 @@ module HaveAPI
       info = auth_field(auth_token_actions(description), action, {})
       input = auth_field(info, :input, {})
       unless [nil, :hash, 'hash', :object, 'object'].include?(auth_field(input, :layout))
-        raise UnsupportedAuthentication, 'This token example requires object input.'
+        raise UnsupportedAuthentication, HaveAPI.t('haveapi.documentation.limitations.token_object_input')
       end
 
       auth_field(input, :parameters, {})
@@ -211,7 +224,7 @@ module HaveAPI
               when 'Boolean' then excluding.include?(false)
               when 'Datetime' then '2026-01-01T00:00:00Z'
               when 'Custom' then {}
-              else raise UnsupportedAuthentication, 'This token example has an unsupported input type.'
+              else raise UnsupportedAuthentication, HaveAPI.t('haveapi.documentation.limitations.token_input_type')
               end
       validators = auth_field(parameter, :validators, {})
       inclusion = auth_field(auth_field(validators, :include, {}), :values)
@@ -220,14 +233,14 @@ module HaveAPI
       if acceptance.is_a?(Hash) && (acceptance.has_key?(:value) || acceptance.has_key?('value'))
         value = auth_field(acceptance, :value)
       elsif values.is_a?(Array)
-        raise UnsupportedAuthentication, 'This token example has no advertised input choice.' if values.empty?
+        raise UnsupportedAuthentication, HaveAPI.t('haveapi.documentation.limitations.token_input_choice_missing') if values.empty?
 
         value = values.find { |choice| !excluding.include?(choice) }
       end
       value = 'fixed' if name.to_s == 'lifetime'
       value = value.to_s if value.is_a?(Symbol) && %w[String Text].include?(type)
       if excluding.include?(value)
-        raise UnsupportedAuthentication, 'This token client cannot send the advertised login input value.'
+        raise UnsupportedAuthentication, HaveAPI.t('haveapi.documentation.limitations.token_input_value')
       end
 
       compatible = case type
@@ -240,7 +253,7 @@ module HaveAPI
                    end
       compatible &&= values.map { |item| item.is_a?(Symbol) ? item.to_s : item }.include?(value) if values.is_a?(Array)
       compatible &&= value == auth_field(acceptance, :value) if acceptance.is_a?(Hash)
-      raise UnsupportedAuthentication, 'This token example cannot represent its advertised input choice.' unless compatible
+      raise UnsupportedAuthentication, HaveAPI.t('haveapi.documentation.limitations.token_input_choice') unless compatible
 
       value
     end

data/lib/haveapi/client_examples/curl.rb

@@ -17,13 +17,13 @@ module HaveAPI::ClientExamples
       case method
       when :basic
         <<~END
-          # Password is asked on standard input
+          #{comment_lines(example_comment('curl_password_stdin', default: 'Password is asked on standard input'), '# ')}
           $ curl --request OPTIONS \\
                  --user user \\
                  #{Shellwords.escape(base_url)}
           # Password: secret
 
-          # Password given on the command line
+          #{comment_lines(example_comment('curl_password_argument', default: 'Password given on the command line'), '# ')}
           $ curl --request OPTIONS \\
                  --user user:secret \\
                  #{Shellwords.escape(base_url)}
@@ -33,20 +33,20 @@ module HaveAPI::ClientExamples
         login = auth_token_credentials(desc)
 
         <<~END
-          # Acquire the token
+          #{comment_lines(example_comment('acquire_token', default: 'Acquire the token'), '# ')}
           $ curl --request POST \\
                  --header 'Content-Type: application/json' \\
                  --data-binary #{Shellwords.escape(JSON.generate(token: login))} \\
                  #{Shellwords.escape(File.join(base_url, '_auth', 'token', 'tokens'))}
 
-          # Use a previously acquired token
+          #{comment_lines(example_comment('use_previous_token', default: 'Use a previously acquired token'), '# ')}
           $ curl --request OPTIONS \\
                  --header #{Shellwords.escape("#{desc[:http_header]}: example-token")} \\
                  #{Shellwords.escape(base_url)}
         END
 
       when :oauth2
-        '# See RFC 6749 for authorization process and RFC 6750 for access token usage.'
+        comment_lines(example_comment('oauth_rfc', default: 'See RFC 6749 for authorization process and RFC 6750 for access token usage.'), '# ')
       end
     rescue HaveAPI::ClientExample::UnsupportedAuthentication => e
       { status: :limitation, reason: e.message }.freeze