docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/developers/known_issues/fixed.md
новий файл +57
−0
1
+
# Виправлені помилки
2
+
3
+
Помилки попередніх версій і версія, з якої їх виправлено. Якщо ви на зачепленій версії — оновіться або скористайтеся обхідним шляхом. Актуальні помилки — на сторінці [Актуальні помилки](/docs/api/json-rpc-bundle/developers/known_issues/open).
4
+
5
+
<include>(.issues/post-response-only-http.md)
6
+
7
+
---
8
+
9
+
<include>(.issues/adapter-routes-overwritten.md)
10
+
11
+
---
12
+
13
+
<include>(.issues/autowire-method-arguments.md)
14
+
15
+
---
16
+
17
+
<include>(.issues/info-concat-ignored.md)
18
+
19
+
---
20
+
21
+
<include>(.issues/deprecated-not-in-openrpc.md)
22
+
23
+
---
24
+
25
+
<include>(.issues/xhr-requests-empty.md)
26
+
27
+
---
28
+
29
+
<include>(.issues/response-cache-shared.md)
30
+
31
+
---
32
+
33
+
<include>(.issues/notifications-without-fpm.md)
34
+
35
+
---
36
+
37
+
<include>(.issues/batch-process-cpu-and-token.md)
38
+
39
+
---
40
+
41
+
<include>(.issues/from-integer-becomes-float.md)
42
+
43
+
---
44
+
45
+
<include>(.issues/terminate-listeners-skipped.md)
46
+
47
+
---
48
+
49
+
<include>(.issues/versioned-routes-issues.md)
50
+
51
+
---
52
+
53
+
<include>(.issues/callback-forwarded-all-headers.md)
54
+
55
+
---
56
+
57
+
<include>(.issues/regressions-8-1.md)
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/post-response-only-http.md
новий файл +12
−0
1
+
### `rpc.post_response` запускалась не для всіх виконаних запитів
2
+
3
+
:::success subtitle="Виправлено в 10.4.2"
4
+
Перевірено за кодом тегів 9.2.1, 10.2.3, 10.4.1 і 10.4.2.
5
+
:::
6
+
7
+
**Симптом.**
8
+
9
+
* **До 10.4.2:** на кожен HTTP-запит чи консольну команду подія генерувалась **один раз** — для останнього `rpc.pre_response`. У процесному batch її отримував лише один запит, а не кожен виконаний.
10
+
* **10.2.x — 10.4.1:** на `kernel.terminate` подія запускалась лише тоді, коли carrier — `RpcFromHttp` цього HTTP-запиту. Для викликів через адаптери (REST тощо) вона не генерувалась, тож не працювали інвалідація `#[RPC\CacheRelation]` і виконання notifications / callback. Для консольних команд подія запускалась.
11
+
12
+
**Виправлення.** Запити збираються в `PostResponseQueue`, і подія генерується один раз на кожен успішно виконаний запит — для будь-якого carrier-а (`IRpcHttpCarrier` або виконання через `RpcExecutor`) і для кожного елемента batch.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/adapter-routes-overwritten.md
новий файл +10
−0
1
+
### Маршрути адаптера затирали один одного в різних групах API
2
+
3
+
:::success subtitle="Виправлено в 10.4.1"
4
+
Зачеплені версії: 10.2.1 — 10.4.0.
5
+
За описом релізу 10.4.1; за кодом не перевірялось.
6
+
:::
7
+
8
+
**Симптом.** Два імпорти того самого `router.yaml` адаптера (наприклад, `/mcp` і `/mcp/internal`) давали однакові назви маршрутів, і другий імпорт затирав перший.
9
+
10
+
**Виправлення.** Адаптер реєструє свій `router.yaml` через `IApiRouteImport`; кожен імпорт отримує назви маршрутів з префіксом групи.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/autowire-method-arguments.md
новий файл +12
−0
1
+
### `#[Autowire]` в аргументах RPC-методу не працював
2
+
3
+
:::success subtitle="Виправлено в 10.3.1"
4
+
Зачеплені версії: 10.0.1 — 10.3.0.
5
+
Перевірено за кодом тегів 10.0.6, 10.2.3 і 10.3.1.
6
+
:::
7
+
8
+
**Симптом.** Сервіс, позначений `#[Autowire]` в аргументі RPC-методу, не підставлявся.
9
+
10
+
**Причина.** `RpcServiceMapPass::processParams()` пропускав кожен типізований параметр, тому такі аргументи не реєструвалися в локаторі методу.
11
+
12
+
**Обхідний шлях для старих версій.** Ін'єкція через конструктор.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/info-concat-ignored.md
новий файл +10
−0
1
+
### `#[RPC\Info(concat: …)]` ігнорувався
2
+
3
+
:::success subtitle="Виправлено в 10.3.1"
4
+
Зачеплені версії: 10.0.0 — 10.3.0.
5
+
Перевірено за кодом тегів 9.2.1, 10.0.6, 10.2.3 і 10.3.1.
6
+
:::
7
+
8
+
**Симптом.** Методи завжди мали роздільник `.` незалежно від `concat`.
9
+
10
+
**Важливо при оновленні.** Після виправлення `concat` знову застосовується: якщо його задано, а клієнти викликають методи через `.`, назви методів зміняться. Оновіть клієнтів або приберіть `concat`.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/deprecated-not-in-openrpc.md
новий файл +10
−0
1
+
### Застарілі методи не позначалися в OpenRPC
2
+
3
+
:::success subtitle="Виправлено в 10.3.1"
4
+
Зачеплені версії: 9.2.1 — 10.3.0.
5
+
Перевірено за кодом тегів 9.1.5, 9.2.1, 10.2.3 і 10.3.1.
6
+
:::
7
+
8
+
**Симптом.** Методи з `@deprecated` або `#[\Deprecated]` не отримували `"deprecated": true` в документації, хоча прапорець збирався в `Service::isDeprecated()`.
9
+
10
+
**Причина.** `OpenRpcAdapter` не передавав прапорець у `OpenRpcSpecBuilder::buildMethod()`.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/xhr-requests-empty.md
новий файл +10
−0
1
+
### XHR-запити отримували порожню відповідь
2
+
3
+
:::success subtitle="Виправлено в 10.3.1"
4
+
Зачеплені версії: 8.0.0 — 10.3.0.
5
+
Перевірено за кодом тегів 8.0.5, 9.2.1, 10.2.3 і 10.3.1.
6
+
:::
7
+
8
+
**Симптом.** POST із заголовком `X-Requested-With: XMLHttpRequest` (наприклад, jQuery `$.ajax`) отримував порожню відповідь `200`, і метод не викликався.
9
+
10
+
**Виправлення.** Порожню відповідь тепер отримує лише CORS preflight `OPTIONS`.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/response-cache-shared.md
новий файл +10
−0
1
+
### Кеш відповідей був спільний для різних реалізацій і версій з однаковою назвою
2
+
3
+
:::success subtitle="Виправлено в 10.3.0"
4
+
Зачеплені версії: 10.0.0 — 10.2.3.
5
+
Перевірено за кодом тегів 10.0.6, 10.2.3 і 10.3.1.
6
+
:::
7
+
8
+
**Симптом.** Однойменні методи різних [версій API](/docs/api/json-rpc-bundle/functionality/versions) або різних [груп](/docs/api/json-rpc-bundle/functionality/groups), реалізовані різними класами, могли отримати кешований результат одне одного.
9
+
10
+
**Виправлення.** Ключ кешу відповідей містить реалізацію (`Class::method`) і версію API. Після оновлення наявний кеш один раз не знайдеться і заповниться заново.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/notifications-without-fpm.md
новий файл +14
−0
1
+
### Notifications не виконувались без PHP-FPM
2
+
3
+
:::success subtitle="Виправлено в 10.3"
4
+
Зачеплені версії: 10.1.0 — 10.2.3. Перевірено за кодом тегів 10.1.0, 10.2.3 і 10.3.1.
5
+
:::
6
+
7
+
**Симптом.**
8
+
9
+
* **10.1.x:** поза PHP-FPM (Apache mod_php, вбудований сервер PHP) виклик `fastcgi_finish_request()` завершувався помилкою, яку бандл мовчки перехоплював, тож `rpc.post_response` не генерувалась і notification не виконувалась узагалі.
10
+
* **10.2.x:** виклик захищено перевіркою `function_exists()`, але без `ignore_user_abort()` PHP обривав виконання, якщо клієнт уже закрив з'єднання, і notification мовчки пропадала.
11
+
12
+
Крім того, виконання друкувало запит і відповідь у stdout через `echo`.
13
+
14
+
**Виправлення.** Notification виконується в будь-якому SAPI, навіть якщо клієнт закрив з'єднання; виконання логується через `LoggerInterface::info()`.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/batch-process-cpu-and-token.md
новий файл +10
−0
1
+
### Процесний batch займав ядро CPU і передавав токен у командному рядку
2
+
3
+
:::success subtitle="Виправлено в 10.3.0"
4
+
Зачеплені версії: до 10.2.3 включно.
5
+
Передача токена аргументом перевірена за кодом тегів 10.2.3 і 10.3.1; навантаження CPU — за описом релізу 10.3.
6
+
:::
7
+
8
+
**Симптом.** Під час процесного batch цикл очікування займав 100% ядра; токен і тіло запиту передавались дочірнім процесам аргументами командного рядка й були видні в списку процесів.
9
+
10
+
**Виправлення.** Без активного циклу очікування; токен передається через змінну `UFO_RPC_TOKEN`, запит — через stdin.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/from-integer-becomes-float.md
новий файл +8
−0
1
+
### `@FROM` перетворював ціле число на дробове
2
+
3
+
:::success subtitle="Виправлено в 10.3.0"
4
+
Зачеплені версії: до 10.2.3 включно (процесний режим batch).
5
+
За описом релізу 10.3; за кодом не перевірялось.
6
+
:::
7
+
8
+
**Симптом.** Цілий результат елемента batch при підстановці в інший елемент через `@FROM:<id>(<поле>)` ставав дробовим, і метод з параметром `int` отримував помилку типу.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/terminate-listeners-skipped.md
новий файл +12
−0
1
+
### Terminate-лістенери застосунку не виконувались після RPC-запитів
2
+
3
+
:::success subtitle="Виправлено в 10.3.0"
4
+
Зачеплені версії: до 10.2.3 включно.
5
+
Перевірено за кодом тегів 9.2.1 — 10.2.3 (зупинка поширення є) і 10.3.1 (немає).
6
+
:::
7
+
8
+
**Симптом.** Лістенери `kernel.terminate` / `console.terminate` застосунку (відправка пошти, flush логів, Sentry тощо) не спрацьовували після RPC-запитів.
9
+
10
+
**Причина.** Бандл зупиняв поширення цих подій.
11
+
12
+
**Важливо при оновленні.** Перевірте лістенери, які раніше мовчки пропускались, — тепер вони виконуються.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/versioned-routes-issues.md
новий файл +8
−0
1
+
### Batch і захист документації на версійних адресах
2
+
3
+
:::success subtitle="Виправлено в 10.2.1"
4
+
Зачеплені версії: 10.0.0 — 10.0.6, 10.1.0.
5
+
За описом релізу 10.2; за кодом не перевірялось.
6
+
:::
7
+
8
+
**Симптом.** Batch-запит на версійну адресу (`/rpc/v2`) виконував елементи у версії за замовчуванням; версійні адреси документації (`/rpc/v2`, `/rpc/v2/postman`) не підпадали під `protected_doc`.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/callback-forwarded-all-headers.md
новий файл +13
−0
1
+
### На callback пересилались усі заголовки клієнта, включно з токеном
2
+
3
+
:::success subtitle="Виправлено в 10.0.6"
4
+
Зачеплені версії: 9.2.0 — 10.0.5. Перевірено за кодом тегів 9.2.1 (усі заголовки) і 10.0.6 (фільтр); проміжні патч-версії 10.0.x окремо не перевірялись.
5
+
:::
6
+
7
+
**Симптом.** Для одиночного HTTP-запиту з `$rpc.callback` сервер копіював усі заголовки вхідного запиту, зокрема RPC-токен (`Ufo-RPC-Token`) та інші облікові дані, у POST-запит на callback URL. Для callback з елементів процесного batch заголовки не пересилались (дочірній процес не має HTTP-запиту).
8
+
9
+
**Причина.** `RpcCallbackProcessor::process()` брав `$httpRequest->headers->all()` без фільтра.
10
+
11
+
**Виправлення.** Пересилаються лише заголовки трасування: `X-Request-Id`, `X-Correlation-Id`, `traceparent`, `tracestate`, `baggage`. Примітки до релізу 9.2 досі описують стару поведінку.
12
+
13
+
**Що зробити, якщо ви були на зачепленій версії.** Якщо клієнти передавали `$rpc.callback` на хости, яким ви не довіряєте, замініть токени, які могли туди потрапити.
uk/docs/api/json-rpc-bundle/developers/known_issues/.issues/regressions-8-1.md
новий файл +10
−0
1
+
### Регресії у версіях 8.1.1–8.1.5
2
+
3
+
:::success subtitle="Виправлено в 8.1.6"
4
+
Зачеплені версії: 8.1.1 — 8.1.5.
5
+
За описом релізу 8.1; за кодом не перевірялось.
6
+
:::
7
+
8
+
**Симптом.** Реліз 8.1.1 відкотив частину змін 8.0.4–8.1.0: схеми enum у документації та спеціальні параметри `$rpc` у `RequestCarrier`.
9
+
10
+
**Виправлення.** Спеціальні параметри — у 8.1.5, схеми enum — у 8.1.6. Не залишайтеся на 8.1.1–8.1.5, використовуйте 8.1.14.