docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/json-rpc-bundle/functionality/async.md
new file +67
ā0
1
+
# Asynchronous processing
2
+
3
+
JsonRpcBundle accepts RPC requests not only over HTTP. The same methods can be called through Symfony Messenger message queues, and even in synchronous requests the server performs part of the work outside the main flow.
4
+
5
+
## Asynchronous processing in synchronous requests
6
+
7
+
* [Batch requests](/docs/api/json-rpc-bundle/functionality/batch) in process mode execute items in parallel in child processes.
8
+
* [Notifications](/docs/api/json-rpc-bundle/functionality/notifications) and requests with [`$rpc.callback`](/docs/api/json-rpc-bundle/functionality/callback) are executed after the response has been sent to the client.
9
+
10
+
## Asynchronous transport (Symfony Messenger)
11
+
12
+
Transports are declared as a list in the `async` block of the [configuration](/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
+
Items with `type: amqp` are registered as [Symfony Messenger](https://symfony.com/doc/current/messenger.html) transports: `name` becomes the transport name, and `RpcAsyncRequest` messages are routed to it (or to `config.route`, if set). The DSN can point to any transport supported by Messenger.
25
+
26
+
To run the RPC server as a queue consumer, run:
27
+
28
+
```bash
29
+
php bin/console messenger:consume rpc_async
30
+
```
31
+
32
+
The consumer validates the token and executes the method. Execution events are dispatched (`rpc.pre_execute`, `rpc.pre_response`, `rpc.post_execute`, `rpc.error`), but **not** `rpc.request` and `rpc.post_response` ā see [Lifecycle](/docs/api/json-rpc-bundle/developers/lifecycle). Token errors and unknown method errors become Messenger message handling errors (retries, failure transport).
33
+
34
+
### Sending a request to the queue
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` defines the [API group](/docs/api/json-rpc-bundle/functionality/groups); without it, `general` is used. The token is validated by the same validator as for HTTP.
44
+
45
+
### Other transport types
46
+
47
+
Items with another `type` (for example, `mercure`) are not connected to Messenger by the bundle. They are available to the application via `RpcAsyncConfig::getConfig(<type>)` and, if `docs.async_dsn_info: true`, are published in the documentation (`x-ufo.transport`) under their `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
+
Declare the transport for failed messages (failure transport) in `framework.messenger` yourself ā the `failed` key in the bundle configuration is not supported since version 9.1.
61
+
:::
62
+
63
+
## Advantages of asynchronous transport
64
+
65
+
1. **Scalability**: the load is distributed among several consumers.
66
+
2. **Reliability**: the broker (RabbitMQ, etc.) guarantees message delivery.
67
+
3. **Single API**: the same methods, validation and security as for HTTP.