docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/config/README.md
новий файл +220
−0
1
+
# Налаштування бандлу
2
+
3
+
:::info
4
+
Ця сторінка описує версію 10.x. Налаштування попередніх версій — у перемикачі версій угорі сторінки.
5
+
:::
6
+
7
+
Усі налаштування знаходяться у файлі `config/packages/ufo_json_rpc.yaml`. Жоден розділ не є обов'язковим: якщо його не вказати, діють значення за замовчуванням.
8
+
9
+
```yaml
10
+
# config/packages/ufo_json_rpc.yaml
11
+
ufo_json_rpc:
12
+
batch:
13
+
enabled: true
14
+
process: true
15
+
process_count: 2
16
+
17
+
notification:
18
+
process: false
19
+
process_count: 2
20
+
21
+
translations:
22
+
paths: []
23
+
24
+
cache:
25
+
ttl: 60
26
+
prefix: 'rpc_cache'
27
+
# pool: 'cache.app'
28
+
29
+
security:
30
+
protected_api: true
31
+
protected_doc: false
32
+
token_name: 'Ufo-RPC-Token'
33
+
clients_tokens:
34
+
- '%env(resolve:UFO_API_TOKEN)%'
35
+
# providers: ...
36
+
37
+
docs:
38
+
project_name: 'My Project'
39
+
project_description: ''
40
+
project_version: null
41
+
async_dsn_info: false
42
+
validations:
43
+
symfony_asserts: false
44
+
45
+
async: []
46
+
```
47
+
48
+
## Блок `security`
49
+
50
+
Захист API ключем доступу (токеном), що передається в HTTP-заголовку.
51
+
52
+
| Параметр | Тип | За замовчуванням | Опис |
53
+
| --- | --- | --- | --- |
54
+
| `protected_api` | `bool` | `true` | Перевіряти токен для RPC-запитів (HTTP, CLI, async) |
55
+
| `protected_doc` | `bool` | `false` | Перевіряти токен для `GET`-запитів документації |
56
+
| `token_name` | `string` | `Ufo-RPC-Token` | Назва заголовка з токеном. У консолі — опція `--<token_name у нижньому регістрі>` |
57
+
| `clients_tokens` | `string[]` | `[]` | Перелік дійсних токенів базового валідатора |
58
+
| `providers` | `map` | — | Окремі валідатори для [груп API](/docs/api/json-rpc-bundle/functionality/groups) |
59
+
60
+
```yaml
61
+
ufo_json_rpc:
62
+
security:
63
+
protected_api: true
64
+
protected_doc: false
65
+
token_name: 'Ufo-RPC-Token'
66
+
clients_tokens:
67
+
- '%env(resolve:UFO_API_TOKEN)%'
68
+
- '%env(resolve:UFO_API_TOKEN_OLD)%' # кілька ключів — для ротації
69
+
```
70
+
71
+
<include>(.http_headers.md)
72
+
73
+
:::danger subtitle="Не зберігайте токени в коді"
74
+
Передавайте токени через змінні оточення (`.env.local`, секрети Symfony), а не прописуйте їх у YAML.
75
+
:::
76
+
77
+
Відсутній токен повертає помилку `-32401` (HTTP 401), недійсний — `-32403`.
78
+
79
+
### Власний валідатор токенів
80
+
81
+
Якщо список токенів не підходить (наприклад, токен — це ключ користувача з бази), реалізуйте `Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator` і підключіть його як базовий валідатор:
82
+
83
+
```php
84
+
use Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator;
85
+
use Ufo\RpcError\RpcInvalidTokenException;
86
+
87
+
final class UserTokenValidator implements ITokenValidator
88
+
{
89
+
public function __construct(private ApiKeyRepository $keys) {}
90
+
91
+
public function isValid(string $token): true
92
+
{
93
+
if (!$this->keys->isActive($token)) {
94
+
throw new RpcInvalidTokenException();
95
+
}
96
+
97
+
return true;
98
+
}
99
+
}
100
+
```
101
+
102
+
```yaml
103
+
# config/services.yaml
104
+
services:
105
+
Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator:
106
+
alias: App\Security\UserTokenValidator
107
+
```
108
+
109
+
Валідатор перевіряє всі захищені точки входу, для яких не призначено окремого провайдера, включно з документацією при `protected_doc: true`.
110
+
111
+
### Провайдери для груп API (`providers`)
112
+
113
+
Кожен провайдер задає **рівно один** з параметрів `service` (сервіс з `ITokenValidator`) або `clients_tokens` (окремий список ключів) і непорожній `api_groups`:
114
+
115
+
```yaml
116
+
ufo_json_rpc:
117
+
security:
118
+
clients_tokens:
119
+
- '%env(resolve:UFO_API_TOKEN)%'
120
+
providers:
121
+
internal:
122
+
api_groups: [internal]
123
+
clients_tokens:
124
+
- '%env(resolve:UFO_INTERNAL_API_TOKEN)%'
125
+
public:
126
+
service: App\Security\UserTokenValidator
127
+
api_groups: [public]
128
+
```
129
+
130
+
Групи без провайдера перевіряє базовий валідатор. Детально — в розділі [Групи API](/docs/api/json-rpc-bundle/functionality/groups).
131
+
132
+
## Блок `docs`
133
+
134
+
Параметри документа [OpenRPC](/docs/api/json-rpc-bundle/documentation).
135
+
136
+
| Параметр | За замовчуванням | Опис |
137
+
| --- | --- | --- |
138
+
| `project_name` | `My Project` | Назва API в документації та колекції Postman |
139
+
| `project_description` | `''` | Опис API |
140
+
| `project_version` | `null` | Версія вашого проєкту (не плутати з [версіями API](/docs/api/json-rpc-bundle/functionality/versions)) |
141
+
| `async_dsn_info` | `false` | Показувати в документації (`x-ufo.transport`) параметри асинхронних транспортів |
142
+
| `validations.symfony_asserts` | `false` | Додавати до параметрів перелік обмежень Symfony (`x-ufo-assertions`) |
143
+
144
+
## Блок `cache`
145
+
146
+
Кеш відповідей методів з [`#[RPC\Cache]`](/docs/api/json-rpc-bundle/add_rpc_service/cache) і кеш документації.
147
+
148
+
| Параметр | За замовчуванням | Опис |
149
+
| --- | --- | --- |
150
+
| `ttl` | `60` | Час життя запису за замовчуванням, секунди |
151
+
| `prefix` | `rpc_cache` | Namespace кешу |
152
+
| `pool` | `null` | Сервіс пулу кешу замість локального файлового пулу `rpc.cache.pool` |
153
+
154
+
```yaml
155
+
ufo_json_rpc:
156
+
cache:
157
+
pool: 'cache.app' # наприклад, спільний Redis
158
+
```
159
+
160
+
`ttl` і `prefix` діють лише для стандартного пулу. На кількох серверах використовуйте спільний пул — тоді інвалідація `#[RPC\CacheRelation]` працює на всіх.
161
+
162
+
## Блок `batch`
163
+
164
+
Обробка [batch-запитів](/docs/api/json-rpc-bundle/functionality/batch).
165
+
166
+
| Параметр | За замовчуванням | Опис |
167
+
| --- | --- | --- |
168
+
| `enabled` | `true` | `false` — batch-запити відхиляються однією помилкою `-32600` |
169
+
| `process` | `true` | `true` — кожен елемент у власному дочірньому процесі `ufo:rpc:process` (ізоляція й паралельність); `false` — по черзі в поточному процесі (inline) |
170
+
| `process_count` | `2` | Скільки дочірніх процесів працюють одночасно (1–10) |
171
+
172
+
:::tip
173
+
Для коротких методів inline-режим (`process: false`) приблизно в 250 разів швидший за процесний.
174
+
:::
175
+
176
+
## Блок `notification`
177
+
178
+
Виконання [notifications](/docs/api/json-rpc-bundle/functionality/notifications) і [`$rpc.callback`](/docs/api/json-rpc-bundle/functionality/callback).
179
+
180
+
| Параметр | За замовчуванням | Опис |
181
+
| --- | --- | --- |
182
+
| `process` | `false` | `true` — виконувати у від'єднаному процесі `ufo:rpc:process`, а не в HTTP-воркері |
183
+
| `process_count` | `2` | Від'єднаних процесів одночасно (1–10); коли всі зайняті — виконується inline |
184
+
185
+
:::warning
186
+
Вмикайте `notification.process` лише для рідкісних довгих notifications: кожен від'єднаний процес завантажує Symfony kernel (~200–300 мс CPU), тож під навантаженням це повільніше за звичайне виконання.
187
+
:::
188
+
189
+
## Блок `translations`
190
+
191
+
Переклади назв і описів методів для документації лежать у `translations/rpc.<locale>.yaml` застосунку. `paths` додає теки з тією самою структурою, наприклад з розширень:
192
+
193
+
```yaml
194
+
ufo_json_rpc:
195
+
translations:
196
+
paths:
197
+
- '%kernel.project_dir%/vendor/acme/rpc-extension/translations'
198
+
```
199
+
200
+
Детально — в розділі [Документація API](/docs/api/json-rpc-bundle/documentation).
201
+
202
+
## Блок `async`
203
+
204
+
Список асинхронних транспортів. Кожен елемент має `type` і довільний `config` (`name`, `dsn` та додаткові ключі):
205
+
206
+
```yaml
207
+
ufo_json_rpc:
208
+
async:
209
+
- type: 'amqp'
210
+
config:
211
+
name: 'rpc_async'
212
+
dsn: '%env(resolve:RPC_TRANSPORT_DSN)%'
213
+
- type: 'mercure'
214
+
config:
215
+
name: 'rpc_socket'
216
+
dsn: '%env(resolve:MERCURE_PUBLIC_URL)%'
217
+
topics_prefix: 'rpc.event.'
218
+
```
219
+
220
+
Елементи з `type: amqp` реєструються як транспорти Symfony Messenger з назвою `name`. Детально — в розділі [Асинхронність](/docs/api/json-rpc-bundle/functionality/async).