docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/developers/known_issues/open.md
новий файл +25
−0
1
+
# Актуальні помилки
2
+
3
+
Відомі помилки й нестиковки поточної версії JsonRpcBundle (10.4.2): симптом, причина та обхідний шлях. Виправлені — на сторінці [Виправлені помилки](/docs/api/json-rpc-bundle/developers/known_issues/fixed).
4
+
5
+
<include>(.issues/lock-waits-instead-of-error.md)
6
+
7
+
---
8
+
9
+
<include>(.issues/rpc-error-not-for-all-http-errors.md)
10
+
11
+
---
12
+
13
+
<include>(.issues/async-request-event-not-fired.md)
14
+
15
+
---
16
+
17
+
<include>(.issues/dto-collection-on-method.md)
18
+
19
+
---
20
+
21
+
<include>(.issues/translations-locales-shared.md)
22
+
23
+
---
24
+
25
+
<include>(.issues/bundle-docs-link.md)
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/lock-waits-instead-of-error.md
новий файл +13
−0
1
+
### `#[RPC\Lock]` чекає звільнення замість помилки «locked»
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 7.4.0 — 10.4.2 (поточна): блокувальний `acquire(true)` є в `RPC\Lock` з першої версії (`ufo-tech/rpc-objects` 2.9.0). Нестиковка між описом релізу 7.4 і поведінкою.
5
+
:::
6
+
7
+
**Симптом.** Опис 7.4 обіцяє, що виклик заблокованого методу завершиться помилкою `-32400` «Method '…' is locked». Насправді паралельний виклик з тим самим ключем чекає, доки перший завершиться, і виконується після нього.
8
+
9
+
**Причина.** `RPC\Lock::acquire()` викликає `$lock->acquire(true)` (блокувальний режим), а сховище `UfoLockerStore` не реалізує `BlockingStoreInterface`. Symfony Lock у такому разі повторює спробу в циклі, поки блокування не звільниться, і `LockConflictedException` назовні не потрапляє.
10
+
11
+
**Наслідки.** Повторні виклики не відхиляються, а накопичуються й тримають воркери. Без `ttl` очікування не обмежене часом.
12
+
13
+
**Обхідний шлях.** Завжди задавайте `ttl`. Якщо потрібна саме відмова, а не черга, перевіряйте зайнятість власним сервісом Symfony Lock з `acquire(false)` усередині методу.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/rpc-error-not-for-all-http-errors.md
новий файл +13
−0
1
+
### `rpc.error` генерується не для всіх помилок одиночного HTTP-запиту
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 10.4.2 (поточна). Нестиковка між точками входу.
5
+
:::
6
+
7
+
**Симптом.** Для одиночного HTTP-запиту частина помилок не проходить через подію `rpc.error` і не пишеться в лог бандла: недійсний JSON, відсутній чи недійсний токен, невідомий метод, непідтримувана версія `jsonrpc`, порожній чи вимкнений batch, нестача позиційних параметрів, виняток з вашого лістенера. Відповідь з помилкою клієнт отримує, але ваші лістенери `rpc.error` її не бачать, і в лог вона не потрапляє взагалі: `SymfonyErrorListener` зупиняє поширення `kernel.exception`, тож не спрацьовує і стандартне логування Symfony (`ErrorListener::logKernelException`).
8
+
9
+
Для тих самих помилок у консолі (`ufo:rpc:process`), inline-batch і через `RpcExecutor` подія `rpc.error` генерується.
10
+
11
+
**Причина.** У HTTP ці винятки перехоплює `SymfonyErrorListener` на `kernel.exception` і одразу формує відповідь.
12
+
13
+
**Обхідний шлях.** Щоб бачити всі помилки HTTP, підпишіться на Symfony `kernel.exception` з пріоритетом вище 999 для маршрутів RPC.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/async-request-event-not-fired.md
новий файл +11
−0
1
+
### Подія `rpc.async_request` оголошена, але не генерується
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 7.0.0 — 10.4.2 (поточна). Перевірено за кодом тегів 7.0.0, 8.0.5, 9.2.1, 10.2.3, 10.4.2: метод `fireAsyncRequest()` ніде не викликається.
5
+
:::
6
+
7
+
**Симптом.** Лістенер на `RpcEvent::REQUEST_ASYNC` (`rpc.async_request`) ніколи не викликається.
8
+
9
+
**Причина.** `RpcEventFactory::fireAsyncRequest()` не викликається в коді бандла. Обробник Symfony Messenger (`RpcAsyncProcessor`) передає запит одразу в `RpcServer::handle()`, оминаючи і `rpc.request`, і `rpc.async_request`.
10
+
11
+
**Обхідний шлях.** Для запитів з черги підписуйтесь на `rpc.pre_execute`: вона генерується для кожного виконання методу незалежно від джерела.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/dto-collection-on-method.md
новий файл +11
−0
1
+
### `#[RPC\DTOCollection]` на методі не задає формат відповіді
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: перевірено за кодом тегів 10.0.6 — 10.4.2 (поточна); `DTOCollection` з'явився в `ufo-tech/rpc-objects` 3.8.2.
5
+
:::
6
+
7
+
**Симптом.** Метод з `#[RPC\DTOCollection(UserDto::class)]` і типом повернення `array` не отримує схему колекції DTO в документації, а елементи результату не обробляються як DTO.
8
+
9
+
**Причина.** `ResponseFiller` читає атрибут через `getAttributes(DTO::class)` без прапорця `ReflectionAttribute::IS_INSTANCEOF`, тож нащадок `DTOCollection` не знаходиться.
10
+
11
+
**Обхідний шлях.** Використовуйте `#[RPC\DTO(UserDto::class, collection: true)]` або вкажіть тип у PHPDoc: `@return UserDto[]`.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/translations-locales-shared.md
новий файл +12
−0
1
+
### Мови перекладів документації спільні для всіх груп API
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 10.4.0 — 10.4.2 (поточна).
5
+
За примітками до релізу 10.4 (розділ «Відомі проблеми»).
6
+
:::
7
+
8
+
**Симптом.** Якщо мова є лише в груповому файлі (наприклад, `translations/rpc/bfa.pl.yaml`), документація іншої групи з `Accept-Language: pl` повертає `Content-Language: pl`, хоча тексти в ній мовою за замовчуванням.
9
+
10
+
**Причина.** Перелік доступних мов збирається один для всіх груп.
11
+
12
+
**Обхідний шлях.** Тримайте однаковий набір мов у базових і групових файлах перекладів.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/bundle-docs-link.md
новий файл +9
−0
1
+
### Застарілі посилання й політики в репозиторії бандла
2
+
3
+
:::warning subtitle="Актуальна"
4
+
Зачеплені версії: 10.4.2 (поточна). Нестиковка документації, на роботу бандла не впливає.
5
+
:::
6
+
7
+
`README.md`, `README-UA.md` і `homepage` у `composer.json` бандла ведуть на стару вікі `docs.ufo-tech.space/bin/view/docs/JsonRpcBundle/`. Актуальна документація — на цьому сайті.
8
+
9
+
У `SECURITY.md` перелік підтримуваних версій закінчується на 6.1.x, хоча актуальна гілка — 10.x.