docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/functionality/async.md
новий файл +67
−0
1
+
# Асинхронність
2
+
3
+
JsonRpcBundle приймає RPC-запити не лише по HTTP. Ті самі методи можна викликати через черги повідомлень Symfony Messenger, а частину роботи навіть у синхронних запитах сервер виконує поза основним потоком.
4
+
5
+
## Асинхронність у синхронних запитах
6
+
7
+
* [Batch-запити](/docs/api/json-rpc-bundle/functionality/batch) у процесному режимі виконують елементи паралельно в дочірніх процесах.
8
+
* [Notifications](/docs/api/json-rpc-bundle/functionality/notifications) і запити з [`$rpc.callback`](/docs/api/json-rpc-bundle/functionality/callback) виконуються після відправлення відповіді клієнту.
9
+
10
+
## Асинхронний транспорт (Symfony Messenger)
11
+
12
+
Транспорти оголошуються списком у блоці `async` [налаштувань](/docs/api/json-rpc-bundle/config):
13
+
14
+
```yaml
15
+
# config/packages/ufo_json_rpc.yaml
16
+
ufo_json_rpc:
17
+
async:
18
+
- type: 'amqp'
19
+
config:
20
+
name: 'rpc_async'
21
+
dsn: '%env(resolve:RPC_TRANSPORT_DSN)%'
22
+
```
23
+
24
+
Елементи з `type: amqp` реєструються як транспорти [Symfony Messenger](https://symfony.com/doc/current/messenger.html): `name` стає назвою транспорту, і повідомлення `RpcAsyncRequest` маршрутизуються на нього (або на `config.route`, якщо задано). DSN може вказувати на будь-який транспорт, який підтримує Messenger.
25
+
26
+
Щоб запустити RPC сервер як споживача черги, виконайте:
27
+
28
+
```bash
29
+
php bin/console messenger:consume rpc_async
30
+
```
31
+
32
+
Споживач перевіряє токен і виконує метод. Генеруються події виконання (`rpc.pre_execute`, `rpc.pre_response`, `rpc.post_execute`, `rpc.error`), але **не** `rpc.request` і `rpc.post_response` — див. [Життєвий цикл](/docs/api/json-rpc-bundle/developers/lifecycle). Помилки токена й невідомого методу стають помилками обробки повідомлення Messenger (повторні спроби, failure transport).
33
+
34
+
### Відправка запиту в чергу
35
+
36
+
```php
37
+
use Symfony\Component\Messenger\MessageBusInterface;
38
+
use Ufo\RpcObject\RpcAsyncRequest;
39
+
40
+
$bus->dispatch(new RpcAsyncRequest($rpcRequest, $token, apiGroup: 'internal'));
41
+
```
42
+
43
+
`apiGroup` визначає [групу API](/docs/api/json-rpc-bundle/functionality/groups); без нього використовується `general`. Токен перевіряється тим самим валідатором, що й для HTTP.
44
+
45
+
### Інші типи транспортів
46
+
47
+
Елементи з іншим `type` (наприклад, `mercure`) бандл до Messenger не підключає. Вони доступні застосунку через `RpcAsyncConfig::getConfig(<type>)` і, якщо `docs.async_dsn_info: true`, публікуються в документації (`x-ufo.transport`) під своїм `name`.
48
+
49
+
```yaml
50
+
ufo_json_rpc:
51
+
async:
52
+
- type: 'mercure'
53
+
config:
54
+
name: 'rpc_socket'
55
+
dsn: '%env(resolve:MERCURE_PUBLIC_URL)%'
56
+
topics_prefix: 'rpc.event.'
57
+
```
58
+
59
+
:::info
60
+
Транспорт для невдалих повідомлень (failure transport) оголошуйте в `framework.messenger` самостійно — ключ `failed` у конфігурації бандла не підтримується з версії 9.1.
61
+
:::
62
+
63
+
## Переваги асинхронного транспорту
64
+
65
+
1. **Масштабованість**: навантаження розподіляється між кількома споживачами.
66
+
2. **Надійність**: брокер (RabbitMQ тощо) гарантує доставку повідомлень.
67
+
3. **Єдиний API**: ті самі методи, валідація й безпека, що й для HTTP.