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

Усі налаштування знаходяться у файлі 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-заголовку.

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)%'   # кілька ключів — для ротації

Відсутній токен повертає помилку -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.

Блок cache

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

ufo_json_rpc:
    cache:
        pool: 'cache.app'   # наприклад, спільний Redis

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

Блок batch

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

Блок notification

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

Блок 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. Детально — в розділі Асинхронність.