haveapi 0.32.1 → 0.32.2

data/doc/cs/readme.md

@@ -0,0 +1,432 @@
+<h1 id="haveapi">HaveAPI</h1>
+
+Serverová implementace protokolu [HaveAPI](https://github.com/vpsfreecz/haveapi)
+v Ruby má podobu frameworku pro tvorbu RESTful webových API, která poskytují
+vlastní popis. Framework obsahuje DSL pro definici zdrojů, akcí a vstupních
+i výstupních parametrů. HaveAPI zajišťuje HTTP komunikaci, autentizaci,
+zpracování vstupních parametrů i formátování výstupu, takže se můžeš soustředit
+na aplikační logiku.
+
+<h2 id="server-framework-features">Funkce serverového frameworku</h2>
+
+- Zajišťuje síťovou komunikaci, autentizaci, autorizaci, vstupní a výstupní
+  formáty i parametry; stačí definovat zdroje a akce
+- Dokumentace vzniká společně s kódem
+- Automaticky generovaná online HTML dokumentace
+- Integrace s ORM
+  - ActiveRecord
+    - propojení s řadičem
+    - načítání a dokumentování validátorů z modelů
+    - přednačítání souvisejících dat
+  - snadné doplnění podpory dalších ORM frameworků
+
+<h2 id="usage">Použití</h2>
+
+Text nemusí být úplný ani aktuální, protože se rozhraní stále často mění.
+Příkladem plného využití HaveAPI je
+[vpsadmin-api](https://github.com/vpsfreecz/vpsadmin-api)
+([online dokumentace](https://api.vpsfree.cz)).
+
+Všechny zdroje a akce představují třídy. Musí být uložené v modulu, jehož
+název se předá HaveAPI. Framework pak projde třídy v tomto modulu a sestaví API.
+
+V tomto dokumentu budou všechny zdroje v modulu `MyAPI`.
+
+<h3 id="example">Příklad</h3>
+
+Základní příklad neukazuje všechny možnosti a funkce.
+
+Předpokládejme tento 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'
+  }
+
+  # Příklad autentizace s heslem v prostém textu
+  def self.authenticate(username, password)
+    u = User.find_by(login: username)
+
+    if u
+      u if u.password == password
+    end
+  end
+end
+```
+
+Zdroj pro uživatele může vypadat takto:
+
+```ruby
+module MyAPI
+  class User < HaveAPI::Resource
+    # Tento zdroj patří do verze 1.
+    # Zdroj může patřit i do více verzí, například [1, 2]
+    version 1
+
+    # Popis zdroje
+    desc 'Manage users'
+
+    # Model ActiveRecord, ze kterého se načtou validátory
+    model ::User
+
+    # Vyžadovat autentizaci; jde o výchozí nastavení
+    auth true
+
+    # Pojmenovaná skupina sdílených parametrů, kterou pak mohou
+    # použít akce.
+    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
+
+    # Akce
+    # Modul HaveAPI::Actions::Default obsahuje pomocné třídy, které definují
+    # HTTP metody a cesty pro obecné akce.
+    class Index < HaveAPI::Actions::Default::Index
+      desc 'List all users'
+
+      # Žádné vstupní parametry
+
+      # Výstupní parametry
+      output(:object_list) do
+        use :id
+        use :common
+      end
+
+      # Určení, zda může aktuální uživatel tuto akci použít.
+      # allow/deny ihned ukončí tento blok.
+      # Výchozím pravidlem je deny.
+      authorize do |u|
+        allow if u.role == 'admin'
+        deny  # deny je implicitní, takže ho lze vynechat
+      end
+
+      # Příklad použití
+      example do
+        request({})
+        response({
+          users: [
+            {
+              id: 1,
+              login: 'myuser',
+              full_name: 'My Very Name'
+            }
+          ]
+        })
+        comment 'Get a list of all users like this'
+      end
+
+      # Pomocná metoda vracející dotaz na všechny uživatele
+      def query
+        ::User.all
+      end
+
+      # Tato metoda se volá, pokud požadavek obsahuje meta[:count] = true
+      def count
+        query.count
+      end
+
+      # Provedení akce a vrácení seznamu
+      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
+```
+
+<h3 id="what-you-get">Výsledek</h3>
+
+Z tohoto kódu HaveAPI vygeneruje API s vlastním popisem. Bude obsahovat zdroj
+`User` s akcemi `Index` a `Create`, kterými můžeš vypsat existující uživatele
+a vytvářet nové.
+
+S API můžeš pracovat pomocí kteréhokoli z dostupných klientů.
+
+<h3 id="run-the-example">Spuštění příkladu</h3>
+
+```ruby
+api = HaveAPI::Server.new(MyAPI)
+
+# Použití HTTP Basic autentizace
+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!
+```
+
+Tím by se měla aplikace spustit pomocí WEBrick. Otevři
+[http://localhost:4567](http://localhost:4567).
+
+- `GET /` – seznam verzí API
+- `GET /doc` – dokumentace HaveAPI
+- `GET /v1/` – dokumentace verze 1
+- `OPTIONS /` – popis celého API
+- `OPTIONS /v1/` – popis verze API 1
+
+a další rozhraní.
+
+<h2 id="localization">Lokalizace</h2>
+
+HaveAPI může pomocí Ruby `i18n` překládat vlastní zprávy v odpovědích,
+validační chyby a popisy validátorů. Struktura JSON obálky zůstává stejná;
+`message`, `errors` i zprávy validátorů v popisu API jsou nadále obyčejné
+řetězce. Řetězce dodané aplikací do `error!` nebo do voleb `message:` vlastních
+validátorů se vracejí beze změny.
+
+Výchozím jazykem je angličtina. Součástí jsou české překlady, které lze vybrat
+hlavičkou `Accept-Language: cs` nebo regionální variantou, například
+`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
+```
+
+Explicitní hlavička požadavku má přednost před resolverem. Resolver se volá
+znovu po autentizaci, takže aplikace může použít jazykové nastavení
+přihlášeného uživatele, pokud klient jazyk nezvolil. Pokud `locale_header`
+určuje vlastní název hlavičky, HaveAPI ji také povolí v odpovědích na CORS
+preflight požadavky. Hodnota hlavičky má stejnou syntaxi jako `Accept-Language`.
+
+Akce mohou používat překlady aplikace předáním odložených zpráv do `error!`
+nebo do voleb validátoru:
+
+```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
+```
+
+Pokud akce potřebuje překlad ihned jako řetězec, použij `api_t(key, **values)`.
+V DSL blocích na úrovni třídy, například `input`, použij
+`HaveAPI.message(key, **values)`.
+
+Popisky a popisy parametrů akcí se mohou překládat v kontextu popisu API.
+Nastav `parameter_i18n_scope` na jmenný prostor překladů aplikace a ponech
+stávající anglické popisky a popisy jako náhradní hodnoty:
+
+```ruby
+api.parameter_i18n_scope = 'my_api'
+
+input do
+  string :hostname,
+         label: 'Hostname',
+         desc: 'VPS hostname'
+end
+```
+
+HaveAPI nejprve hledá přesný klíč parametru akce:
+
+```yaml
+cs:
+  my_api:
+    resources:
+      vps:
+        actions:
+          create:
+            input:
+              hostname:
+                label: "Hostname"
+                description: "Nazev VPS"
+```
+
+Vygenerovaná cesta je
+`resources.<resource_path>.actions.<action>.<input|output>.<name>`.
+U parametrů metadat zahrnuje také typ metadat a směr, například
+`resources.vps.actions.create.meta.global.output.action_state_id.label`.
+
+Pokud přesný klíč chybí, HaveAPI hledá mezi vstupními a výstupními klíči
+zdroje, atributy zdroje a nakonec sdílenými atributy:
+
+```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"
+```
+
+Popisky voleb deklarovaných validátorem `choices`/`include` používají stejnou
+cestu metadat parametru s připojeným `choices.<value>.label`. Pokud jsou volby
+zadané jako mapa hodnot na popisky, použije se deklarovaný popisek jako
+anglická náhradní hodnota. Pokud jsou zadané jako pole, nepřeložený popis API
+zachová formát pole; jazyk, který poskytuje popisky, vrací existující formát
+mapy HaveAPI `{value: label}`.
+
+```yaml
+cs:
+  my_api:
+    resources:
+      vps:
+        attributes:
+          state:
+            choices:
+              running:
+                label: "bezi"
+              stopped:
+                label: "vypnuto"
+```
+
+U parametrů metadat se jako náhrada hledají klíče metadat zdroje a globálních metadat:
+
+```yaml
+cs:
+  my_api:
+    resources:
+      vps:
+        meta:
+          global:
+            output:
+              count:
+                label: "Return item count"
+    meta:
+      global:
+        output:
+          count:
+            label: "Return item count"
+```
+
+Vlastní metadata HaveAPI, například stránkování a vestavěné meta parametry,
+překládá přímo HaveAPI a nehledá je v jmenném prostoru parametrů aplikace.
+Pokud parametr potřebuje explicitní klíč, který nevychází z jeho umístění
+v akci, použij `label_key` a `desc_key`:
+
+```ruby
+string :hostname,
+       label: 'Hostname',
+       desc: 'VPS hostname',
+       label_key: 'my_api.attributes.hostname.label',
+       desc_key: 'my_api.attributes.hostname.description'
+```
+
+HaveAPI také zpřístupňuje `api.parameter_metadata_i18n_items` pro nástroje,
+které z deklarovaných parametrů generují katalogy překladů aplikace.
+
+<h3 id="run-with-rackup">Spuštění pomocí rackup</h3>
+
+Použij stejný kód jako výše, pouze poslední řádek nahraď tímto:
+
+```ruby
+run api.app
+```
+
+<h2 id="authentication">Autentizace</h2>
+
+HaveAPI definuje rozhraní pro poskytovatele autentizace. Vestavěná je HTTP
+Basic autentizace a autentizace tokenem.
+
+Možnosti autentizace jsou součástí popisu API. Klient si může zvolit metodu,
+které rozumí a kterou chce použít.
+
+<h2 id="authorization">Autorizace</h2>
+
+HaveAPI poskytuje prostředky pro autorizaci přístupu uživatelů k akcím.
+Tento proces není součástí popisu API.
+
+Pokud je uživatel při požadavku na popis API přihlášený, vrátí se pouze
+zdroje, akce a parametry, ke kterým má přístup.
+
+<h2 id="validation-of-input-data">Validace vstupních dat</h2>
+
+Validátory jsou součástí dokumentace API, takže klienti mohou validovat data
+ještě před jejich odesláním na server.
+
+<h2 id="blocking-actions">Blokující akce</h2>
+
+Blokující režim slouží pro akce, jejichž provedení není okamžité a trvá
+předem neurčenou dobu. Protokol HaveAPI umožňuje klientům sledovat jejich
+průběh nebo je zrušit.
+
+<h2 id="contributing">Přispívání</h2>
+
+1. Vytvoř fork ( https://github.com/vpsfreecz/haveapi/fork )
+2. Vytvoř větev pro svou změnu (`git checkout -b my-new-feature`)
+3. Vytvoř commit se změnami (`git commit -am 'Add some feature'`)
+4. Odešli větev (`git push origin my-new-feature`)
+5. Vytvoř nový pull request

data/doc/cs/typed-input-validation.md

@@ -0,0 +1,122 @@
+<h1 id="typed-input-validation">Validace typovaných vstupů</h1>
+
+<h2 id="overview">Přehled</h2>
+
+Parametry HaveAPI deklarují `type` (String, Text, Integer, Float, Boolean, Datetime nebo Resource).
+Servery i klienti MUSÍ typované vstupní parametry přísně validovat.
+Neplatné hodnoty se NESMÍ tiše převádět na výchozí hodnoty jako `0`, `0.0` nebo `false`.
+
+<h2 id="general-rules">Obecná pravidla</h2>
+
+- Skalární typy přijímají pouze skalární hodnoty. Pole, seznamy, objekty a hashe jsou neplatné.
+- Pro účely validace znamená `null`/`nil` „hodnota vynechána“ (server může použít výchozí hodnotu),
+  ale explicitní `null` je platný pouze u parametrů označených jako `nullable` (obvykle nepovinných).
+  Klienti MUSÍ explicitní `null` zachovat a odeslat jako JSON `null`, aby akce rozlišily
+  vynechanou hodnotu od výslovně vymazané.
+- Prázdné řetězce (`""` nebo řetězce obsahující jen bílé znaky) jsou pro Integer, Float, Boolean a Datetime neplatné.
+  U typovaných parametrů s `nullable` (včetně ID zdrojů) se prázdný řetězec nebo bílé znaky považují
+  za `null`/vynechanou hodnotu. To umožňuje vyjádřit explicitní `null` v query stringu.
+- Validace na straně klienta se doporučuje; rozhodující je validace serveru.
+
+Příklad query stringu (explicitní `null` pro typovaný parametr s `nullable`):
+
+    GET /resource/action?resource[dt]=
+
+Prázdná hodnota se u typovaných parametrů s `nullable` považuje za `null`.
+
+<h2 id="per-type-rules-with-examples">Pravidla a příklady pro jednotlivé typy</h2>
+
+<h3 id="integer">Integer</h3>
+
+Přijímá:
+- celé číslo v JSON (např. `12`, `-7`)
+- řetězec odpovídající celému číslu v desítkové soustavě `^[+-]?\d+$` po odstranění krajních bílých znaků (např. `"42"`, `"+5"`)
+- konečné číslo s plovoucí řádovou čárkou, které má celočíselnou hodnotu (např. `12.0`)
+
+Odmítá:
+- nečíselné řetězce (`"abc"`, `"12abc"`)
+- desetinné řetězce (`"12.0"`) a čísla s nenulovou desetinnou částí (`12.3`)
+- prázdný řetězec nebo řetězec obsahující jen bílé znaky
+
+<h3 id="float">Float</h3>
+
+Přijímá:
+- celé číslo nebo číslo s plovoucí řádovou čárkou v JSON (pouze konečné)
+- řetězec obsahující po odstranění krajních bílých znaků úplný zápis čísla, včetně exponentu (např. `"1e3"`, `"-0.5"`)
+
+Odmítá:
+- nečíselné řetězce
+- prázdný řetězec nebo řetězec obsahující jen bílé znaky
+- nekonečné hodnoty a hodnoty, které nejsou číslem (`NaN`, `Infinity`)
+
+Poznámka: celá čísla se pro Float přijímají a převádějí na čísla s plovoucí řádovou čárkou.
+
+<h3 id="boolean">Boolean</h3>
+
+Přijímá:
+- logickou hodnotu v JSON
+- celé číslo `0`/`1`
+- následující řetězce (bez rozlišení velikosti písmen, po odstranění krajních bílých znaků):
+  - pravda: `true`, `t`, `yes`, `y`, `1`
+  - nepravda: `false`, `f`, `no`, `n`, `0`
+
+Odmítá:
+- prázdný řetězec nebo řetězec obsahující jen bílé znaky
+- neznámé řetězce (`"maybe"`)
+- čísla jiná než 0/1
+
+<h3 id="datetime">Datetime</h3>
+
+Přijímá (přenášený formát): řetězce s datem nebo datem a časem podle ISO 8601:
+- `YYYY-MM-DD`
+- `YYYY-MM-DDTHH:MM(:SS(.sss)?)?(Z|+HH:MM|-HH:MM|+HHMM|-HHMM)`
+
+Příklady: `"2020-01-31"`, `"2020-01-31T10:20Z"`, `"2020-01-31T10:20:30.123-0500"`.
+
+Odmítá:
+- prázdný řetězec nebo řetězec obsahující jen bílé znaky
+- jiné formáty než ISO (`2020/01/01`)
+- neplatná kalendářní data (`2020-02-30`)
+
+Poznámka: někteří klienti mohou přijímat nativní objekty Date/Time a serializovat je do ISO 8601.
+
+<h3 id="string-text-rule-6-b">String / Text (pravidlo 6.B)</h3>
+
+Přijímá:
+- skalární hodnoty (řetězec, číslo, logická hodnota) a převádí je na řetězec
+
+Odmítá:
+- pole a seznamy
+- objekty a hashe
+
+<h3 id="resource">Resource</h3>
+
+V přenášených datech jsou vstupem identifikátory zdrojů.
+
+Přijímá:
+- celočíselné ID
+- ID jako řetězec číslic po odstranění krajních bílých znaků
+- u některých klientů ResourceInstance, ze které použije `id`
+- prázdný řetězec nebo řetězec obsahující jen bílé znaky jako `null`/vynechanou hodnotu, pokud má parametr `nullable`
+
+Odmítá:
+- prázdný řetězec nebo řetězec obsahující jen bílé znaky u povinných parametrů
+- řetězce obsahující jiné znaky než číslice
+- záporná ID
+
+Pokud se server pokusí zdroj dohledat a zdroj neexistuje, MUSÍ vrátit validační chybu
+("resource not found"), nikoli chybu 500.
+
+<h2 id="error-reporting-expectations">Očekávané hlášení chyb</h2>
+
+- Server hlásí neplatné typované hodnoty jako chyby validace parametrů ("input parameters are not valid").
+- Klienti by měli pokud možno chybu zachytit ihned lokálně a hlásit ji pro jednotlivé parametry.
+
+Doporučené jednotné zprávy používané klienty:
+- `not a valid integer`
+- `not a valid float`
+- `not a valid boolean`
+- `not in ISO 8601 format`
+- `not a valid string`
+- `not a valid resource ID`
+- `cannot be null`

data/doc/{client-examples.md → en/client-examples.md}

@@ -62,7 +62,7 @@ api.mount('/api/')
 `generator_version` defaults to the server's `HaveAPI::VERSION`. Install the
 matching generator in the server's Ruby environment: `haveapi-go-client`,
 `haveapi-rust-client`, or the source-distributed `haveapi-typescript-client`.
-See the [TypeScript generator guide](../clients/typescript/README.md) for its
+See the [TypeScript generator guide](../../clients/typescript/README.md) for its
 setup. An explicit `generator_version` requires the installed generator to report
 that version; the server never downloads one. This version is independent of the
 API client and API versions.
@@ -96,7 +96,7 @@ go get example.org/widget/client@latest
 cargo add widget-client
 # Blocking Rust variant:
 cargo add widget-client --features blocking
-npm install @example/widget-client haveapi-client@0.30.2
+npm install @example/widget-client haveapi-client@0.32.0
 ```
 
 Go resolves `@latest` by its normal rules. Cargo selects a compatible release
@@ -114,7 +114,7 @@ users can install; the server does not check its availability or publish it.
 TypeScript examples call the package's typed properties through its public
 `createClient` export. The profile does not detect or select the application's
 installed `haveapi-client` runtime. The installation command above uses the
-version supported by the [TypeScript generator](../clients/typescript/README.md);
+version supported by the [TypeScript generator](../../clients/typescript/README.md);
 the examples do not report it as a configured runtime version.
 
 For an unpublished Rust API client, supply an HTTPS Git URL and a full commit SHA:
@@ -209,6 +209,16 @@ wire requests or persisted data.
 
 ## Renderer extensions
 
+Framework-authored explanatory comments follow the documentation language.
+Executable code, identifiers, literals, commented commands and sample data stay
+unchanged. The immutable context captures `locale`, defaulting to `:en`, and
+retains it through `with`. `example_comment(key, default:, **values)` resolves
+`haveapi.documentation.comments.<key>`; `documentation_message` resolves other
+keys relative to `haveapi.documentation`, including generated-client limitations.
+Renderers add a comment marker to every physical prose line. Documentation
+adapters can use these optional context methods without depending on the server
+gem; old contexts and direct renderer calls keep English defaults.
+
 Existing renderer positional constructors and `init`, `auth(method, desc)` and
 `example(sample)` or `request(sample)`/`response(sample)` methods still work.
 The registry binds a request-local `HaveAPI::ClientExample::Context` through
@@ -385,17 +395,17 @@ When changing a renderer:
 - Inspect relevant initialization, authentication and action output for affected
   variants and both direct detail inputs. Cover absent optional fragments and
   literal edge cases where the change can affect them.
-- Use existing [server example specs](../servers/ruby/spec/client_examples/) for
+- Use existing [server example specs](../../servers/ruby/spec/client_examples/) for
   PHP literal round trips and real handlers, Ruby syntax, Python AST/separation,
   detail behavior and custom whitespace. Use the owning
-  [Go documentation specs](../clients/go/spec/unit/documentation_spec.rb),
-  [TypeScript documentation specs](../clients/typescript/spec/unit/) and
-  [Rust development checks](../clients/rust/docs/development.md) when affected.
+  [Go documentation specs](../../clients/go/spec/unit/documentation_spec.rb),
+  [TypeScript documentation specs](../../clients/typescript/spec/unit/) and
+  [Rust development checks](../../clients/rust/docs/development.md) when affected.
   TypeScript coverage includes source, strict compilation and performance specs.
 - Search neighboring HTML, fixture and performance assertions for exact source
   spelling. Update intentional quote/import/spacing expectations while retaining
   semantic assertions, traversal/allocation bounds and strict compiler checks.
-- Follow [development commands](agent-instructions/development.md) and the
+- Follow [development commands](../agent-instructions/development.md) and the
   existing verification requirements. Select checks by affected language and
   behavior; an unrelated edit does not require every language toolchain.
 
@@ -488,7 +498,7 @@ This command runs outside Bundler and records the gem versions actually
 activated. Retain that list alongside both component locks and use the same
 prepared inputs for both revisions. Missing optional dependencies fail the run;
 Rust lanes are never silently omitted. See the
-[Rust adapter guide](../clients/rust/docs/documentation.md#verification).
+[Rust adapter guide](../../clients/rust/docs/documentation.md#verification).
 
 Every lane reports each trial and the median wall seconds, process CPU seconds
 and allocated objects, with the operation count per trial. Wall time uses a
@@ -528,4 +538,4 @@ installed packages or an API client. These run rendered source against
 disposable fixtures; syntax checks alone do not
 establish that client calls or authentication work. See each client's
 development documentation for its test environment. Highlighter rebuilding is
-described in [utils/highlight](../utils/highlight/README.md).
+described in [utils/highlight](../../utils/highlight/README.md).