docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/json-rpc-bundle/config/README.md
new file +220
ā0
1
+
# Bundle configuration
2
+
3
+
:::info
4
+
This page describes version 10.x. Configuration for earlier versions is available in the version selector at the top of the page.
5
+
:::
6
+
7
+
All configuration lives in `config/packages/ufo_json_rpc.yaml`. No section is required: if a section is omitted, the default values apply.
8
+
9
+
```yaml
10
+
# config/packages/ufo_json_rpc.yaml
11
+
ufo_json_rpc:
12
+
batch:
13
+
enabled: true
14
+
process: true
15
+
process_count: 2
16
+
17
+
notification:
18
+
process: false
19
+
process_count: 2
20
+
21
+
translations:
22
+
paths: []
23
+
24
+
cache:
25
+
ttl: 60
26
+
prefix: 'rpc_cache'
27
+
# pool: 'cache.app'
28
+
29
+
security:
30
+
protected_api: true
31
+
protected_doc: false
32
+
token_name: 'Ufo-RPC-Token'
33
+
clients_tokens:
34
+
- '%env(resolve:UFO_API_TOKEN)%'
35
+
# providers: ...
36
+
37
+
docs:
38
+
project_name: 'My Project'
39
+
project_description: ''
40
+
project_version: null
41
+
async_dsn_info: false
42
+
validations:
43
+
symfony_asserts: false
44
+
45
+
async: []
46
+
```
47
+
48
+
## The `security` block
49
+
50
+
Protects the API with an access key (token) passed in an HTTP header.
51
+
52
+
| Parameter | Type | Default | Description |
53
+
| --- | --- | --- | --- |
54
+
| `protected_api` | `bool` | `true` | Check the token for RPC requests (HTTP, CLI, async) |
55
+
| `protected_doc` | `bool` | `false` | Check the token for documentation `GET` requests |
56
+
| `token_name` | `string` | `Ufo-RPC-Token` | Name of the header carrying the token. In the console, it is the `--<token_name in lowercase>` option |
57
+
| `clients_tokens` | `string[]` | `[]` | List of valid tokens for the base validator |
58
+
| `providers` | `map` | ā | Separate validators for [API groups](/docs/api/json-rpc-bundle/functionality/groups) |
59
+
60
+
```yaml
61
+
ufo_json_rpc:
62
+
security:
63
+
protected_api: true
64
+
protected_doc: false
65
+
token_name: 'Ufo-RPC-Token'
66
+
clients_tokens:
67
+
- '%env(resolve:UFO_API_TOKEN)%'
68
+
- '%env(resolve:UFO_API_TOKEN_OLD)%' # multiple keys, for rotation
69
+
```
70
+
71
+
<include>(.http_headers.md)
72
+
73
+
:::danger subtitle="Do not store tokens in code"
74
+
Pass tokens via environment variables (`.env.local`, Symfony secrets) instead of hardcoding them in YAML.
75
+
:::
76
+
77
+
A missing token returns error `-32401` (HTTP 401), an invalid one returns `-32403`.
78
+
79
+
### Custom token validator
80
+
81
+
If a token list does not fit your case (for example, the token is a user key stored in the database), implement `Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator` and register it as the base validator:
82
+
83
+
```php
84
+
use Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator;
85
+
use Ufo\RpcError\RpcInvalidTokenException;
86
+
87
+
final class UserTokenValidator implements ITokenValidator
88
+
{
89
+
public function __construct(private ApiKeyRepository $keys) {}
90
+
91
+
public function isValid(string $token): true
92
+
{
93
+
if (!$this->keys->isActive($token)) {
94
+
throw new RpcInvalidTokenException();
95
+
}
96
+
97
+
return true;
98
+
}
99
+
}
100
+
```
101
+
102
+
```yaml
103
+
# config/services.yaml
104
+
services:
105
+
Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator:
106
+
alias: App\Security\UserTokenValidator
107
+
```
108
+
109
+
The validator checks all protected entry points that have no dedicated provider assigned, including the documentation when `protected_doc: true`.
110
+
111
+
### Providers for API groups (`providers`)
112
+
113
+
Each provider sets **exactly one** of `service` (a service implementing `ITokenValidator`) or `clients_tokens` (a separate list of keys), plus a non-empty `api_groups`:
114
+
115
+
```yaml
116
+
ufo_json_rpc:
117
+
security:
118
+
clients_tokens:
119
+
- '%env(resolve:UFO_API_TOKEN)%'
120
+
providers:
121
+
internal:
122
+
api_groups: [internal]
123
+
clients_tokens:
124
+
- '%env(resolve:UFO_INTERNAL_API_TOKEN)%'
125
+
public:
126
+
service: App\Security\UserTokenValidator
127
+
api_groups: [public]
128
+
```
129
+
130
+
Groups without a provider are checked by the base validator. See [API groups](/docs/api/json-rpc-bundle/functionality/groups) for details.
131
+
132
+
## The `docs` block
133
+
134
+
Parameters of the [OpenRPC](/docs/api/json-rpc-bundle/documentation) document.
135
+
136
+
| Parameter | Default | Description |
137
+
| --- | --- | --- |
138
+
| `project_name` | `My Project` | API name in the documentation and the Postman collection |
139
+
| `project_description` | `''` | API description |
140
+
| `project_version` | `null` | Version of your project (not to be confused with [API versions](/docs/api/json-rpc-bundle/functionality/versions)) |
141
+
| `async_dsn_info` | `false` | Show the parameters of asynchronous transports in the documentation (`x-ufo.transport`) |
142
+
| `validations.symfony_asserts` | `false` | Add the list of Symfony constraints to parameters (`x-ufo-assertions`) |
143
+
144
+
## The `cache` block
145
+
146
+
Response cache for methods with [`#[RPC\Cache]`](/docs/api/json-rpc-bundle/add_rpc_service/cache) and the documentation cache.
147
+
148
+
| Parameter | Default | Description |
149
+
| --- | --- | --- |
150
+
| `ttl` | `60` | Default entry lifetime, in seconds |
151
+
| `prefix` | `rpc_cache` | Cache namespace |
152
+
| `pool` | `null` | Cache pool service to use instead of the local file pool `rpc.cache.pool` |
153
+
154
+
```yaml
155
+
ufo_json_rpc:
156
+
cache:
157
+
pool: 'cache.app' # e.g. a shared Redis
158
+
```
159
+
160
+
`ttl` and `prefix` apply only to the default pool. On multiple servers, use a shared pool so that `#[RPC\CacheRelation]` invalidation works on all of them.
161
+
162
+
## The `batch` block
163
+
164
+
Processing of [batch requests](/docs/api/json-rpc-bundle/functionality/batch).
165
+
166
+
| Parameter | Default | Description |
167
+
| --- | --- | --- |
168
+
| `enabled` | `true` | `false`: batch requests are rejected with a single `-32600` error |
169
+
| `process` | `true` | `true`: each item runs in its own `ufo:rpc:process` child process (isolation and parallelism); `false`: items run one by one in the current process (inline) |
170
+
| `process_count` | `2` | How many child processes run concurrently (1ā10) |
171
+
172
+
:::tip
173
+
For short methods, inline mode (`process: false`) is roughly 250 times faster than process mode.
174
+
:::
175
+
176
+
## The `notification` block
177
+
178
+
Execution of [notifications](/docs/api/json-rpc-bundle/functionality/notifications) and [`$rpc.callback`](/docs/api/json-rpc-bundle/functionality/callback).
179
+
180
+
| Parameter | Default | Description |
181
+
| --- | --- | --- |
182
+
| `process` | `false` | `true`: run in a detached `ufo:rpc:process` process instead of the HTTP worker |
183
+
| `process_count` | `2` | Detached processes running concurrently (1ā10); when all are busy, execution happens inline |
184
+
185
+
:::warning
186
+
Enable `notification.process` only for rare long-running notifications: each detached process boots the Symfony kernel (~200ā300 ms CPU), so under load this is slower than regular execution.
187
+
:::
188
+
189
+
## The `translations` block
190
+
191
+
Translations of method names and descriptions for the documentation live in the application's `translations/rpc.<locale>.yaml`. `paths` adds directories with the same structure, for example from extensions:
192
+
193
+
```yaml
194
+
ufo_json_rpc:
195
+
translations:
196
+
paths:
197
+
- '%kernel.project_dir%/vendor/acme/rpc-extension/translations'
198
+
```
199
+
200
+
See [API documentation](/docs/api/json-rpc-bundle/documentation) for details.
201
+
202
+
## The `async` block
203
+
204
+
List of asynchronous transports. Each item has a `type` and an arbitrary `config` (`name`, `dsn` and additional keys):
205
+
206
+
```yaml
207
+
ufo_json_rpc:
208
+
async:
209
+
- type: 'amqp'
210
+
config:
211
+
name: 'rpc_async'
212
+
dsn: '%env(resolve:RPC_TRANSPORT_DSN)%'
213
+
- type: 'mercure'
214
+
config:
215
+
name: 'rpc_socket'
216
+
dsn: '%env(resolve:MERCURE_PUBLIC_URL)%'
217
+
topics_prefix: 'rpc.event.'
218
+
```
219
+
220
+
Items with `type: amqp` are registered as Symfony Messenger transports named `name`. See [Asynchronous processing](/docs/api/json-rpc-bundle/functionality/async) for details.
en/docs/api/json-rpc-bundle/config/.http_headers.md
new file +11
ā0
1
+
::::info
2
+
:::spoiler subtitle="HTTP header naming requirements"
3
+
HTTP header names are not strictly regulated with respect to capitalization, because HTTP headers are case-insensitive. However, there are some common practices and standards that are usually followed for better readability and consistency:
4
+
5
+
- Capitalization: HTTP header names are usually written in CamelCase, where each word starts with a capital letter, e.g. Content-Type, User-Agent, Accept-Encoding. This does not affect how headers are processed technically, but makes them easier to read.
6
+
- Uniqueness: Each header must have a unique name within a single HTTP request or response. The same name cannot be used for different headers in the same request or response.
7
+
- Special headers: Some headers are used specifically to control caching behavior (Cache-Control), security (Strict-Transport-Security), authentication (Authorization), etc.
8
+
- RFC norms: Header requirements are governed by RFC documents, which define the standards for Internet protocols. For example, general headers and their usage are described in RFC 7231.
9
+
10
+
:::
11
+
::::