docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/json-rpc-bundle/functionality/notifications.md
new file +50
ā0
1
+
# Notifications
2
+
3
+
:::info
4
+
Available since version 10.1.
5
+
:::
6
+
7
+
Per the JSON-RPC 2.0 specification, a request without an `id` is a notification: the client does not wait for a result. The server does not return a response to it, and a single notification over HTTP gets `204 No Content` with an empty body.
8
+
9
+
```bash
10
+
curl -i -X POST https://example.com/rpc \
11
+
-H 'Content-Type: application/json' -H 'Ufo-RPC-Token: <token>' \
12
+
-d '{"jsonrpc": "2.0", "method": "audit.log", "params": {"event": "login"}}'
13
+
# HTTP/1.1 204 No Content
14
+
```
15
+
16
+
The method signature does not change; its result is discarded. So notifications suit "fire and forget" actions: auditing, metrics, sending messages.
17
+
18
+
## When the method runs
19
+
20
+
The method runs on the `rpc.post_response` event, i.e. **after** the response has been sent to the client:
21
+
22
+
* under PHP-FPM, after `fastcgi_finish_request()`, so the client does not wait;
23
+
* in other SAPIs (Apache mod_php, the built-in server) the method also runs, even if the client has already closed the connection (since 10.3), but the HTTP worker stays busy until the method finishes.
24
+
25
+
Execution is logged via `LoggerInterface` at the `info` level.
26
+
27
+
## Detached execution
28
+
29
+
Rare long-running notifications can be executed in a detached `ufo:rpc:process` process so they do not hold the HTTP worker:
30
+
31
+
```yaml
32
+
ufo_json_rpc:
33
+
notification:
34
+
process: true
35
+
process_count: 2 # detached processes running concurrently (1ā10); when all are busy, execution happens inline
36
+
```
37
+
38
+
The request is executed exactly once: if the detached process has not picked it up within 3 seconds, the worker executes it itself. The same applies to [`$rpc.callback`](/docs/api/json-rpc-bundle/functionality/callback).
39
+
40
+
:::warning
41
+
Each detached process boots the Symfony kernel (~200ā300 ms CPU). Under load this is slower than regular execution, so enable the option only for rare long-running methods.
42
+
:::
43
+
44
+
## Notifications in batch
45
+
46
+
In a [batch](/docs/api/json-rpc-bundle/functionality/batch), a notification is executed according to the batch mode, but there is no response for it. A batch containing only notifications returns `204` with no body.
47
+
48
+
## Upgrading from 10.0
49
+
50
+
Clients that sent requests without an `id` and waited for a result must pass an `id`.