Bundle configuration

All configuration lives in config/packages/ufo_json_rpc.yaml. No section is required: if a section is omitted, the default values apply.

# 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: []

The security block

Protects the API with an access key (token) passed in an HTTP header.

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)%'   # multiple keys, for rotation

<include>(.http_headers.md)

A missing token returns error -32401 (HTTP 401), an invalid one returns -32403.

Custom token validator

If a token list does not fit your case (for example, the token is a user key stored in the database), implement Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator and register it as the base validator:

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

The validator checks all protected entry points that have no dedicated provider assigned, including the documentation when protected_doc: true.

Providers for API groups (providers)

Each provider sets exactly one of service (a service implementing ITokenValidator) or clients_tokens (a separate list of keys), plus a non-empty 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]

Groups without a provider are checked by the base validator. See API groups for details.

The docs block

Parameters of the OpenRPC document.

The cache block

Response cache for methods with #[RPC\Cache] and the documentation cache.

ufo_json_rpc:
    cache:
        pool: 'cache.app'   # e.g. a shared Redis

ttl and prefix apply only to the default pool. On multiple servers, use a shared pool so that #[RPC\CacheRelation] invalidation works on all of them.

The batch block

Processing of batch requests.

The notification block

Execution of notifications and $rpc.callback.

The translations block

Translations of method names and descriptions for the documentation live in the application's translations/rpc.<locale>.yaml. paths adds directories with the same structure, for example from extensions:

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

See API documentation for details.

The async block

List of asynchronous transports. Each item has a type and an arbitrary config (name, dsn and additional keys):

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.'

Items with type: amqp are registered as Symfony Messenger transports named name. See Asynchronous processing for details.