Налаштування бандлу

← Налаштування бандлу

Ashterix

docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api

uk/docs/api/json-rpc-bundle/config/README.md новий файл +220 −0

Налаштування бандлу

Ця сторінка описує версію 10.x. Налаштування попередніх версій — у перемикачі версій угорі сторінки.

Усі налаштування знаходяться у файлі config/packages/ufo_json_rpc.yaml. Жоден розділ не є обов'язковим: якщо його не вказати, діють значення за замовчуванням.

# config/packages/ufo_json_rpc.yaml
ufo_json_rpc:
    batch:
        enabled: true
        process: true
        process_count: 2

    notification:
        process: false
        process_count: 2

    translations:
        paths: []

    cache:
        ttl: 60
        prefix: 'rpc_cache'
        # pool: 'cache.app'

    security:
        protected_api: true
        protected_doc: false
        token_name: 'Ufo-RPC-Token'
        clients_tokens:
            - '%env(resolve:UFO_API_TOKEN)%'
        # providers: ...

    docs:
        project_name: 'My Project'
        project_description: ''
        project_version: null
        async_dsn_info: false
        validations:
            symfony_asserts: false

    async: []

Блок security

Захист API ключем доступу (токеном), що передається в HTTP-заголовку.

Параметр Тип За замовчуванням Опис
protected_api bool true Перевіряти токен для RPC-запитів (HTTP, CLI, async)
protected_doc bool false Перевіряти токен для GET-запитів документації
token_name string Ufo-RPC-Token Назва заголовка з токеном. У консолі — опція --<token_name у нижньому регістрі>
clients_tokens string[] [] Перелік дійсних токенів базового валідатора
providers map — Окремі валідатори для груп API 
ufo_json_rpc:
    security:
        protected_api: true
        protected_doc: false
        token_name: 'Ufo-RPC-Token'
        clients_tokens:
            - '%env(resolve:UFO_API_TOKEN)%'
            - '%env(resolve:UFO_API_TOKEN_OLD)%'   # кілька ключів — для ротації

<include>(.http_headers.md)

Не зберігайте токени в коді

Передавайте токени через змінні оточення (.env.local, секрети Symfony), а не прописуйте їх у YAML.

Відсутній токен повертає помилку -32401 (HTTP 401), недійсний — -32403.

Власний валідатор токенів

Якщо список токенів не підходить (наприклад, токен — це ключ користувача з бази), реалізуйте Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator і підключіть його як базовий валідатор:

use Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator;
use Ufo\RpcError\RpcInvalidTokenException;

final class UserTokenValidator implements ITokenValidator
{
    public function __construct(private ApiKeyRepository $keys) {}

    public function isValid(string $token): true
    {
        if (!$this->keys->isActive($token)) {
            throw new RpcInvalidTokenException();
        }

        return true;
    }
}

# config/services.yaml
services:
    Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator:
        alias: App\Security\UserTokenValidator

Валідатор перевіряє всі захищені точки входу, для яких не призначено окремого провайдера, включно з документацією при protected_doc: true.

Провайдери для груп API (providers)

Кожен провайдер задає рівно один з параметрів service (сервіс з ITokenValidator) або clients_tokens (окремий список ключів) і непорожній api_groups:

ufo_json_rpc:
    security:
        clients_tokens:
            - '%env(resolve:UFO_API_TOKEN)%'
        providers:
            internal:
                api_groups: [internal]
                clients_tokens:
                    - '%env(resolve:UFO_INTERNAL_API_TOKEN)%'
            public:
                service: App\Security\UserTokenValidator
                api_groups: [public]

Групи без провайдера перевіряє базовий валідатор. Детально — в розділі Групи API.

Блок docs

Параметри документа OpenRPC.

Параметр За замовчуванням Опис
project_name My Project Назва API в документації та колекції Postman
project_description '' Опис API
project_version null Версія вашого проєкту (не плутати з версіями API)
async_dsn_info false Показувати в документації (x-ufo.transport) параметри асинхронних транспортів
validations.symfony_asserts false Додавати до параметрів перелік обмежень Symfony (x-ufo-assertions)

Блок cache

Кеш відповідей методів з #[RPC\Cache] і кеш документації.

Параметр За замовчуванням Опис
ttl 60 Час життя запису за замовчуванням, секунди
prefix rpc_cache Namespace кешу
pool null Сервіс пулу кешу замість локального файлового пулу rpc.cache.pool 
ufo_json_rpc:
    cache:
        pool: 'cache.app'   # наприклад, спільний Redis

ttl і prefix діють лише для стандартного пулу. На кількох серверах використовуйте спільний пул — тоді інвалідація #[RPC\CacheRelation] працює на всіх.

Блок batch

Обробка batch-запитів.

Параметр За замовчуванням Опис
enabled true false — batch-запити відхиляються однією помилкою -32600
process true true — кожен елемент у власному дочірньому процесі ufo:rpc:process (ізоляція й паралельність); false — по черзі в поточному процесі (inline)
process_count 2 Скільки дочірніх процесів працюють одночасно (1–10)

Для коротких методів inline-режим (process: false) приблизно в 250 разів швидший за процесний.

Блок notification

Виконання notifications і $rpc.callback.

Параметр За замовчуванням Опис
process false true — виконувати у від'єднаному процесі ufo:rpc:process, а не в HTTP-воркері
process_count 2 Від'єднаних процесів одночасно (1–10); коли всі зайняті — виконується inline

Вмикайте notification.process лише для рідкісних довгих notifications: кожен від'єднаний процес завантажує Symfony kernel (~200–300 мс CPU), тож під навантаженням це повільніше за звичайне виконання.

Блок translations

Переклади назв і описів методів для документації лежать у translations/rpc.<locale>.yaml застосунку. paths додає теки з тією самою структурою, наприклад з розширень:

ufo_json_rpc:
    translations:
        paths:
            - '%kernel.project_dir%/vendor/acme/rpc-extension/translations'

Детально — в розділі Документація API.

Блок async

Список асинхронних транспортів. Кожен елемент має type і довільний config (name, dsn та додаткові ключі):

ufo_json_rpc:
    async:
        - type: 'amqp'
          config:
              name: 'rpc_async'
              dsn: '%env(resolve:RPC_TRANSPORT_DSN)%'
        - type: 'mercure'
          config:
              name: 'rpc_socket'
              dsn: '%env(resolve:MERCURE_PUBLIC_URL)%'
              topics_prefix: 'rpc.event.'

Елементи з type: amqp реєструються як транспорти Symfony Messenger з назвою name. Детально — в розділі Асинхронність.