docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/functionality/events/request.md
новий файл +113
−0
1
+
# rpc.request
2
+
3
+
::::::block class="floatinginfobox floatinginfobox--fit"
4
+
:::::columns border zebra
5
+
::::row
6
+
:::col width="40%"
7
+
**Назва події**
8
+
:::
9
+
:::col
10
+
`rpc.request`
11
+
:::
12
+
::::
13
+
::::row
14
+
:::col width="40%"
15
+
**Константа**
16
+
:::
17
+
:::col
18
+
`RpcEvent::REQUEST`
19
+
:::
20
+
::::
21
+
::::row
22
+
:::col width="40%"
23
+
**Клас**
24
+
:::
25
+
:::col
26
+
`RpcRequestEvent`
27
+
:::
28
+
::::
29
+
::::row
30
+
:::col width="40%"
31
+
**Властивості**
32
+
:::
33
+
:::col
34
+
`RpcRequest $rpcRequest`
35
+
:::
36
+
::::
37
+
::::row
38
+
:::col width="40%"
39
+
**Вбудовані лістенери**
40
+
:::
41
+
:::col
42
+
немає
43
+
:::
44
+
::::
45
+
:::::
46
+
::::::
47
+
48
+
Перша RPC-подія запиту: генерується після розбору JSON, перевірки токена й версії `jsonrpc`, але **до** перевірки кешу і виклику методу.
49
+
50
+
## Коли генерується
51
+
52
+
* Одиночний HTTP-запит і виклик з консолі — один раз.
53
+
* Batch: для кожного елемента. У процесному режимі — у дочірньому процесі, а не в батьківському.
54
+
* Notifications і `$rpc.callback` — один раз при прийомі; під час відкладеного виконання методу повторно не генерується.
55
+
* Виклики через `RpcExecutor` (адаптери REST, MCP) — для кожного запиту.
56
+
57
+
**Не генерується** для повідомлень з Symfony Messenger, для запитів прогріву кешу і для запитів, відхилених раніше (недійсний JSON, помилка токена).
58
+
59
+
## Що можна змінити
60
+
61
+
* Присвоєння нового `$event->rpcRequest` **ні на що не впливає** — обробник працює з власним посиланням на запит.
62
+
* Змінювати сам об'єкт запиту можна. `$event->rpcRequest->setError($exception)` змушує запит завершитися помилкою ще до виклику методу (перевіряється на `rpc.pre_execute`). На кешовану відповідь і на прийом notifications/callback це не впливає.
63
+
* Виняток з лістенера повертає клієнту помилку.
64
+
65
+
## Приклади використання
66
+
67
+
### Трасування
68
+
69
+
Прив'язати запит до ідентифікатора трасування — `rayId` зі спеціальних параметрів або власного заголовка:
70
+
71
+
```php
72
+
#[AsEventListener(RpcEvent::REQUEST)]
73
+
final class TraceListener
74
+
{
75
+
public function __construct(private LoggerInterface $logger) {}
76
+
77
+
public function __invoke(RpcRequestEvent $event): void
78
+
{
79
+
$request = $event->rpcRequest;
80
+
$this->logger->info('rpc.request', [
81
+
'method' => $request->getMethod(),
82
+
'id' => $request instanceof RpcNotificationRequest ? null : $request->getId(),
83
+
'ray_id' => $request->getRpcParams()?->getRayId(),
84
+
'version' => $request->apiVersion,
85
+
]);
86
+
}
87
+
}
88
+
```
89
+
90
+
### Технічне обслуговування
91
+
92
+
Тимчасово відхиляти виклики окремих методів (наприклад, на час міграції):
93
+
94
+
```php
95
+
#[AsEventListener(RpcEvent::REQUEST)]
96
+
final class MaintenanceListener
97
+
{
98
+
public function __construct(private FeatureFlags $flags) {}
99
+
100
+
public function __invoke(RpcRequestEvent $event): void
101
+
{
102
+
if ($this->flags->isFrozen($event->rpcRequest->getMethod())) {
103
+
$event->rpcRequest->setError(new RpcLogicException('Method is temporarily unavailable'));
104
+
}
105
+
}
106
+
}
107
+
```
108
+
109
+
### Інші ідеї
110
+
111
+
* лічильник викликів методів (rate limiting за клієнтом);
112
+
* збір статистики використання застарілих методів;
113
+
* перевірка додаткових умов доступу до методу (роль, тариф клієнта).