docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/json-rpc-bundle/developers/known_issues/open.md
new file +25
ā0
1
+
# Open issues
2
+
3
+
Known bugs and inconsistencies in the current version of JsonRpcBundle (10.4.2): symptom, cause and workaround. Fixed ones are on the [Fixed issues](/docs/api/json-rpc-bundle/developers/known_issues/fixed) page.
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)
en/docs/api/json-rpc-bundle/developers/known_issues/.issues/lock-waits-instead-of-error.md
new file +13
ā0
1
+
### `#[RPC\Lock]` waits for release instead of a "locked" error
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: 7.4.0 ā 10.4.2 (current): the blocking `acquire(true)` has been in `RPC\Lock` since its first version (`ufo-tech/rpc-objects` 2.9.0). An inconsistency between the 7.4 release notes and the behavior.
5
+
:::
6
+
7
+
**Symptom.** The 7.4 notes promise that calling a locked method ends with error `-32400` "Method 'ā¦' is locked". In fact, a parallel call with the same key waits until the first one finishes and is executed after it.
8
+
9
+
**Cause.** `RPC\Lock::acquire()` calls `$lock->acquire(true)` (blocking mode), and the `UfoLockerStore` store does not implement `BlockingStoreInterface`. In this case Symfony Lock retries in a loop until the lock is released, and `LockConflictedException` never surfaces.
10
+
11
+
**Consequences.** Repeated calls are not rejected but pile up and hold workers. Without `ttl` the wait is not limited in time.
12
+
13
+
**Workaround.** Always set `ttl`. If you need an actual rejection rather than a queue, check whether the lock is taken with your own Symfony Lock service using `acquire(false)` inside the method.
en/docs/api/json-rpc-bundle/developers/known_issues/.issues/rpc-error-not-for-all-http-errors.md
new file +13
ā0
1
+
### `rpc.error` is not fired for all errors of a single HTTP request
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: 10.4.2 (current). An inconsistency between entry points.
5
+
:::
6
+
7
+
**Symptom.** For a single HTTP request, some errors do not go through the `rpc.error` event and are not written to the bundle's log: invalid JSON, missing or invalid token, unknown method, unsupported `jsonrpc` version, empty or disabled batch, missing positional parameters, an exception from your listener. The client does receive the error response, but your `rpc.error` listeners do not see it, and it does not get logged at all: `SymfonyErrorListener` stops propagation of `kernel.exception`, so the standard Symfony logging (`ErrorListener::logKernelException`) does not run either.
8
+
9
+
For the same errors in the console (`ufo:rpc:process`), inline batch and via `RpcExecutor`, the `rpc.error` event is fired.
10
+
11
+
**Cause.** In HTTP, these exceptions are caught by `SymfonyErrorListener` on `kernel.exception`, which immediately builds the response.
12
+
13
+
**Workaround.** To see all HTTP errors, subscribe to Symfony's `kernel.exception` with a priority higher than 999 for RPC routes.
en/docs/api/json-rpc-bundle/developers/known_issues/.issues/async-request-event-not-fired.md
new file +11
ā0
1
+
### The `rpc.async_request` event is declared but never fired
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: 7.0.0 ā 10.4.2 (current). Verified against the code of tags 7.0.0, 8.0.5, 9.2.1, 10.2.3, 10.4.2: the `fireAsyncRequest()` method is not called anywhere.
5
+
:::
6
+
7
+
**Symptom.** A listener on `RpcEvent::REQUEST_ASYNC` (`rpc.async_request`) is never called.
8
+
9
+
**Cause.** `RpcEventFactory::fireAsyncRequest()` is not called in the bundle's code. The Symfony Messenger handler (`RpcAsyncProcessor`) passes the request straight to `RpcServer::handle()`, bypassing both `rpc.request` and `rpc.async_request`.
10
+
11
+
**Workaround.** For requests from the queue, subscribe to `rpc.pre_execute`: it is fired for every method execution regardless of the source.
en/docs/api/json-rpc-bundle/developers/known_issues/.issues/dto-collection-on-method.md
new file +11
ā0
1
+
### `#[RPC\DTOCollection]` on a method does not set the response format
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: verified against the code of tags 10.0.6 ā 10.4.2 (current); `DTOCollection` appeared in `ufo-tech/rpc-objects` 3.8.2.
5
+
:::
6
+
7
+
**Symptom.** A method with `#[RPC\DTOCollection(UserDto::class)]` and return type `array` does not get a DTO collection schema in the documentation, and the result items are not processed as DTOs.
8
+
9
+
**Cause.** `ResponseFiller` reads the attribute via `getAttributes(DTO::class)` without the `ReflectionAttribute::IS_INSTANCEOF` flag, so the `DTOCollection` subclass is not found.
10
+
11
+
**Workaround.** Use `#[RPC\DTO(UserDto::class, collection: true)]` or specify the type in PHPDoc: `@return UserDto[]`.
en/docs/api/json-rpc-bundle/developers/known_issues/.issues/translations-locales-shared.md
new file +12
ā0
1
+
### Documentation translation languages are shared across all API groups
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: 10.4.0 ā 10.4.2 (current).
5
+
Based on the 10.4 release notes ("Known issues" section).
6
+
:::
7
+
8
+
**Symptom.** If a language exists only in a group file (for example, `translations/rpc/bfa.pl.yaml`), the documentation of another group with `Accept-Language: pl` returns `Content-Language: pl`, although its texts are in the default language.
9
+
10
+
**Cause.** The list of available languages is collected once for all groups.
11
+
12
+
**Workaround.** Keep the same set of languages in the base and group translation files.
en/docs/api/json-rpc-bundle/developers/known_issues/.issues/bundle-docs-link.md
new file +9
ā0
1
+
### Outdated links and policies in the bundle repository
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: 10.4.2 (current). A documentation inconsistency; does not affect how the bundle works.
5
+
:::
6
+
7
+
`README.md`, `README-UA.md` and `homepage` in the bundle's `composer.json` point to the old wiki `docs.ufo-tech.space/bin/view/docs/JsonRpcBundle/`. The up-to-date documentation is on this site.
8
+
9
+
In `SECURITY.md`, the list of supported versions ends at 6.1.x, although the current branch is 10.x.