docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/functionality/batch.md
+41
−34
96
96
97
97
1. **Спрощення бекенду:** Замість того, щоб кожен раз реалізовувати специфічну логіку на боці бекенду, можна винести це на рівень побудови клієнтських запитів.
98
98
2. **Зменшення кількості мережевих запитів**: Замість надсилання декількох HTTP-запитів, що може створювати навантаження на мережу та сервер, використовується лише один запит. Це значно знижує навантаження на мережу та серверні ресурси.
99
−
3. **Час відповіді**: RPC Server віддасть результат всіх запитів не зважаючи на їх кількість за стільки часу, скільки необхідно на обробку найдовшого запиту з пакету, тому що обробка всіх запитів відбувається [паралельно](/docs/json-rpc-bundle/functionality/batch/#H42F43A44643543F44043044644E454).
99
+
3. **Час відповіді**: RPC Server віддасть результат всіх запитів не зважаючи на їх кількість за стільки часу, скільки необхідно на обробку найдовшого запиту з пакету, тому що обробка всіх запитів відбувається [паралельно](/docs/api/json-rpc-bundle/functionality/batch/).
100
100
4. **Зменшення часу затримки**: Виконання декількох запитів в одному з'єднанні може знизити загальний час затримки, оскільки зменшується кількість часу, витраченого на встановлення та завершення з'єднань.
101
101
5. **Оптимізація використання ресурсів клієнта та сервера**: Оскільки менше запитів обробляється одночасно, знижується навантаження на сервер, що дозволяє йому обробляти більше запитів. Клієнт також використовує менше ресурсів, що може бути критичним для мобільних та обмежених пристроїв.
102
102
6. **Покращена керованість транзакцій**: Коли декілька операцій необхідно виконати атомарно (усі або жодна), batch запит дозволяє це зробити легше, оскільки усі операції виконуються в межах одного запиту.
103
103
104
104
### Підготовка до використання
105
105
106
−
Функціональність batch запитів доступна одразу і не вимагає додаткових налаштувань з боку розробника.
106
+
Batch-запити доступні одразу. Як саме виконуються елементи, задає блок `batch` у [налаштуваннях](/docs/api/json-rpc-bundle/config) — див. розділ «Режими виконання» нижче.
107
107
108
108
### Послідовність запитів
109
109
110
−
Послідовність наповнення batch не має значення, бо на RPC сервері всі запити виконуються паралельно і ви отримаєте відповідь із швидкістю найдовшого запиту з переліку.
111
−
112
−
Якщо в якомусь запиті з переліку відбудеться помилка, це ніяк не впливає на опрацювання інших запитів з переліку.
110
+
Порядок елементів у batch не має значення. Помилка в одному елементі не впливає на обробку інших: у відповіді для нього буде об'єкт `error`, для решти — `result`.
113
111
114
112
### Залежні запити
115
113
128
126
```json
129
127
[
130
128
{
129
+
"jsonrpc": "2.0",
131
130
"id":"example_1",
132
131
"method":"UserService.getInfo",
133
132
"params":{
135
134
}
136
135
},
137
136
{
137
+
"jsonrpc": "2.0",
138
138
"id":"example_2",
139
139
"method":"Messenger.sendEmail",
140
140
"params":{
170
170
:::
171
171
::::
172
172
173
+
Формат залежності: `@FROM:<id запиту>(<поле результату>)`. Залежності працюють в обох режимах виконання.
174
+
173
175
У цьому прикладі:
174
176
175
177
1. Перший запит отримує інформацію про користувача з id 141, включаючи його емейл.
189
191
2. **Зменшення кількості мережевих запитів**: Усі запити об'єднуються в один, що знижує навантаження на мережу.
190
192
3. **Гнучкість**: Можливість створювати складні сценарії запитів без необхідності додаткових налаштувань чи змін на бекенді.
191
193
192
−
## Як це працює
194
+
## Режими виконання
193
195
194
−
Механізм обробки batch запитів працює асинхронно.
196
+
```yaml
197
+
# config/packages/ufo_json_rpc.yaml
198
+
ufo_json_rpc:
199
+
batch:
200
+
enabled: true # false: batch-запити відхиляються однією помилкою -32600 "Batch requests are disabled"
201
+
process: true # true: кожен елемент у дочірньому процесі; false: по черзі в поточному процесі
202
+
process_count: 2 # процесний режим: скільки дочірніх процесів одночасно (1–10)
203
+
```
195
204
196
−
Отримуючи масив запитів RPC Server створює чергу з [Symfony Process](https://symfony.com/doc/current/components/process.html), тобто запускає CLI команди, які обробляються асинхронно. В циклі while стан процесів перевіряється, і якщо отримано результат, він додається до масиву відповідей. Якщо ж відповіді немає до закінчення таймауту, повертається помилка про те, що запит не оброблено.
205
+
| Режим | Як працює | Коли обирати |
206
+
| --- | --- | --- |
207
+
| процесний (`process: true`, за замовчуванням) | Кожен елемент виконується в окремому процесі `ufo:rpc:process` ([Symfony Process](https://symfony.com/doc/current/components/process.html)); одночасно працює не більше `process_count` процесів, решта чекає | Довгі незалежні методи, яким потрібні ізоляція й паралельність |
208
+
| inline (`process: false`) | Елементи виконуються послідовно в поточному процесі | Короткі методи: приблизно в 250 разів швидше, бо не запускається PHP-процес на кожен елемент |
197
209
198
−
### Алгоритм
210
+
:::warning subtitle="Оновлення до 10.3"
211
+
З 10.3 `process_count` за замовчуванням 2, тож великі batch у процесному режимі виконуються повільніше, ніж раніше. Поставте `process_count: 10` або перейдіть на `process: false`.
212
+
:::
199
213
200
−
* Batch запит розбивається на окремі запити, кожен з яких додається до черги.
201
−
* В циклі перевіряється наявність об’єктів у черзі.
202
−
* Для кожного об'єкту черги перевіряється, чи завершився процес.
203
−
* Якщо процес завершився, результат додається до масиву відповідей, а процес видаляється з черги.
204
−
* Якщо процес не завершився і таймаут ще не вийшов, цикл продовжується.
205
−
* Якщо таймаут вийшов до отримання результату, для конкретного запиту повертається помилка про те, що запит не оброблено.
214
+
Токен передається дочірнім процесам через змінну оточення `UFO_RPC_TOKEN`, а запит — через stdin, тож вони не потрапляють у список процесів. Дочірні процеси зберігають [групу](/docs/api/json-rpc-bundle/functionality/groups) й [версію](/docs/api/json-rpc-bundle/functionality/versions) API маршруту.
206
215
207
−
Щоб збільшити таймаут у batch запиті, в параметрах конкретного запиту можна вказати додатковий службовий параметр $rpc.timeout - максимальна кількість секунд очікування відповіді від процеса. За замовчуванням значення таймауту становить 10 секунд.
216
+
### Таймаут елемента
208
217
209
−
**Request**
218
+
У процесному режимі відповідь елемента очікується обмежений час: за замовчуванням 10 секунд. Якщо результату немає, для цього елемента повертається помилка. Для довгих методів таймаут збільшують спеціальним параметром `$rpc.timeout`:
210
219
211
220
```json
212
−
[
213
−
{
214
−
"id":"example_1",
215
−
"method":"ExampleApi.fastMethod",
216
−
"params":{
217
−
"someParam": "someValue"
218
−
}
219
−
},
220
−
{
221
−
"id":"example_2",
222
−
"method":"ExampleApi.longMethod",
223
−
"params":{
224
−
"someParam": "someValue",
225
−
"$rpc.timeout": 30
226
−
}
227
−
}
221
+
[
222
+
{"jsonrpc": "2.0", "id": "example_1", "method": "ExampleApi.fastMethod", "params": {"someParam": "someValue"}},
223
+
{"jsonrpc": "2.0", "id": "example_2", "method": "ExampleApi.longMethod", "params": {"someParam": "someValue", "$rpc": {"timeout": 30}}}
228
224
]
229
225
```
230
226
231
−
Це дозволяє налаштувати тривалість очікування результатів для методів, що потенційно можуть працювати довго, що може бути важливо для обробки деяких запитів.
227
+
## Notifications у batch
228
+
229
+
Елемент без `id` — [notification](/docs/api/json-rpc-bundle/functionality/notifications). За специфікацією JSON-RPC 2.0 відповіді на нього немає:
230
+
231
+
* notification виконується згідно з режимом batch, але у відповіді лише інші елементи;
232
+
* batch лише з notifications повертає `204` без тіла;
233
+
* notification, чия залежність `@FROM` не виконалась, не виконується.
234
+
235
+
## Помилки batch
236
+
237
+
* Порожній batch `[]` — одна помилка `-32600` (`Can't process empty batch request`).
238
+
* Batch при `batch.enabled: false` — одна помилка `-32600` (`Batch requests are disabled`).