haveapi 0.32.1 → 0.32.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fef6937fc8c3a3f3ae382a0c6032ae6fcc7900ad9fb6480aed9a9f3c43556c7d
-  data.tar.gz: 4339642a36b69c79396e92fcba4acdd3cb13292a63a0afac90b9dfe22c0d4920
+  metadata.gz: c137421451f1521e445bf3e6d0316413a46775fb2a74d527908f4b03814441b9
+  data.tar.gz: 8a7a91920805fb36e27f5d8a8791a6b08a5a9721b8c90e49a9a53db42070f3a8
 SHA512:
-  metadata.gz: 632a7cb540320f32451ff939e1d6044dd75a8382cd7d32ac0858a1a82533509c1e3935b73904d44f30b3226b4bec337b729d4a870aa4691adcbbfc0ab1c2da9a
-  data.tar.gz: ed900045161d35036c3dd5002f395f0ca05e2db1a7d12327c74be483c2adafd2b554cc49313fd3a5ea089c29a9a16069f2d41d009dc3130b7784be4b9c588b42
+  metadata.gz: 25f59af897385a659412428247f02cf1290f0b56e8cd6bdf071b40eb263d1d750bf6b89329c2bd810d16264eb0520169fc54db2e367230bce26f65cfb6187440
+  data.tar.gz: 3ed4c37dd4a6138f9a7e4a8fbb762dd38d1d6cf78422bf0d02d5aa3bc8d6052ee3379d45d010ae8c3566e67e4e0fd68ae14c293c513d035b9e16a7a6bc222142

data/.gitignore

@@ -1,8 +1,3 @@
-doc/protocol.*
-doc/create-client.md
-doc/typed-input-validation.md
-doc/client-examples.md
-doc/documentation-ui.md
-doc/documentation-oauth.md
-doc/performance.md
-doc/json-schema.html
+doc/en/
+doc/cs/
+doc/protocol.png

data/README.md

@@ -1,423 +1,4 @@
-# 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.
+# HaveAPI Ruby server
 
-## 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
+See the [server framework guide](../../doc/en/readme.md) for usage,
+authentication, authorization and localization.

data/Rakefile

@@ -9,12 +9,22 @@ require 'haveapi/tasks/yard'
 desc 'Check shared documentation required in the server gem'
 task :check_doc do
   required = %w[
-    doc/json-schema.html
-    doc/protocol.md
-    doc/create-client.md
-    doc/typed-input-validation.md
-    doc/client-examples.md
     doc/protocol.png
+    doc/en/readme.md
+    doc/en/protocol.md
+    doc/en/create-client.md
+    doc/en/typed-input-validation.md
+    doc/en/client-examples.md
+    doc/en/documentation-ui.md
+    doc/en/documentation-oauth.md
+    doc/en/performance.md
+    doc/en/json-schema.html
+    doc/cs/readme.md
+    doc/cs/protocol.md
+    doc/cs/create-client.md
+    doc/cs/typed-input-validation.md
+    doc/cs/client-examples.md
+    doc/cs/json-schema.html
   ]
   missing = required.reject { |path| File.file?(path) && File.size?(path) }
 
@@ -40,11 +50,11 @@ begin
       '--protected',
       '--output-dir=html_doc',
       '--files=doc/*.md',
-      '--files=doc/*.html'
+      '--files=doc/en/*.md',
+      '--files=doc/en/*.html'
     ]
     t.before = proc do
       document_hooks.call
-      render_doc_file('doc/json-schema.erb', 'doc/JSON-Schema.html').call
     end
   end
 rescue LoadError

data/benchmarks/performance_compare.rb

@@ -245,8 +245,14 @@ module HaveAPI
       COMPONENTS = Release::VERSIONS
       SPECS = COMPONENTS.to_h { |path, name| ["#{path.split('/lib/').first}/#{name}.gemspec", name] }.freeze
       PATHS = (['VERSION'] + COMPONENTS.keys + SPECS.keys).freeze
-
-      def self.capture(contents)
+      SERVER_GEMSPEC = 'servers/ruby/haveapi.gemspec'.freeze
+      FILE_SELECTION_POLICY = 'documentation-files-v1'.freeze
+      FILE_SELECTIONS = [
+        "  s.files       = `git ls-files -z`.split(\"\\x0\") + Dir.glob('doc/*')\n",
+        "  s.files       = `git ls-files -z`.split(\"\\x0\") + Dir.glob('doc/**/*').select { |path| File.file?(path) }\n"
+      ].freeze
+
+      def self.capture(contents, normalize_files: true)
         raise ContractError, 'Incomplete own source metadata' unless contents.keys.sort == PATHS.sort
 
         own = contents.fetch('VERSION').delete_suffix("\n")
@@ -284,9 +290,22 @@ module HaveAPI
             normalized[path] = text.sub(requirement, "'haveapi-client', '~> #{PLACEHOLDER}'")
           end
         end
-        { 'contents' => contents, 'own_version' => own,
-          'raw_sha256' => contents.transform_values { |text| Digest::SHA256.hexdigest(text) },
-          'normalized_sha256' => normalized.transform_values { |text| Digest::SHA256.hexdigest(text) } }
+        files = normalize_files && documentation_files(normalized.fetch(SERVER_GEMSPEC))
+        normalized[SERVER_GEMSPEC] = files if files
+        receipt = { 'contents' => contents, 'own_version' => own,
+                    'raw_sha256' => contents.transform_values { |text| Digest::SHA256.hexdigest(text) },
+                    'normalized_sha256' => normalized.transform_values { |text| Digest::SHA256.hexdigest(text) } }
+        receipt['file_selection'] = FILE_SELECTION_POLICY if files
+        receipt
+      end
+
+      # This reviewed packaging transition does not change the dependency graph.
+      # Unknown or ambiguous declarations retain their original strict bytes.
+      def self.documentation_files(text)
+        declarations = text.lines.grep(/^\s*s\.files\b/)
+        return unless declarations.length == 1 && FILE_SELECTIONS.include?(declarations.first)
+
+        text.sub(declarations.first, "  s.files       = DOCUMENTATION_FILES\n")
       end
 
       def self.gemspec(root, path, receipt)
@@ -307,7 +326,9 @@ module HaveAPI
 
       def self.validate_inputs(inputs, source)
         receipt = inputs.fetch('source_versions')
-        raise ContractError, 'Own source metadata normalization mismatch' unless receipt == capture(receipt.fetch('contents'))
+        # Marker-absent legacy receipts used raw file-selection statements.
+        expected = capture(receipt.fetch('contents'), normalize_files: receipt.has_key?('file_selection'))
+        raise ContractError, 'Own source metadata normalization mismatch' unless receipt == expected
 
         receipt.fetch('raw_sha256').each do |path, digest|
           unless source.fetch('files_sha256').fetch(path) == digest && inputs.fetch('manifests').fetch(path) == receipt.fetch('normalized_sha256').fetch(path)