volucer-worker 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- volucer_worker-0.1.0/LICENSE +21 -0
- volucer_worker-0.1.0/PKG-INFO +448 -0
- volucer_worker-0.1.0/README.md +425 -0
- volucer_worker-0.1.0/pyproject.toml +43 -0
- volucer_worker-0.1.0/setup.cfg +4 -0
- volucer_worker-0.1.0/tests/test_end_to_end.py +671 -0
- volucer_worker-0.1.0/tests/test_rpc.py +596 -0
- volucer_worker-0.1.0/tests/test_wire_format.py +216 -0
- volucer_worker-0.1.0/tests/test_worker.py +574 -0
- volucer_worker-0.1.0/tests/test_wsgi.py +202 -0
- volucer_worker-0.1.0/volucer_worker/__init__.py +112 -0
- volucer_worker-0.1.0/volucer_worker/grpc.py +102 -0
- volucer_worker-0.1.0/volucer_worker/message.py +172 -0
- volucer_worker-0.1.0/volucer_worker/protocol.py +279 -0
- volucer_worker-0.1.0/volucer_worker/py.typed +0 -0
- volucer_worker-0.1.0/volucer_worker/rpc.py +782 -0
- volucer_worker-0.1.0/volucer_worker/supervisor.py +341 -0
- volucer_worker-0.1.0/volucer_worker/worker.py +1001 -0
- volucer_worker-0.1.0/volucer_worker/wsgi.py +229 -0
- volucer_worker-0.1.0/volucer_worker.egg-info/PKG-INFO +448 -0
- volucer_worker-0.1.0/volucer_worker.egg-info/SOURCES.txt +21 -0
- volucer_worker-0.1.0/volucer_worker.egg-info/dependency_links.txt +1 -0
- volucer_worker-0.1.0/volucer_worker.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Sailantis
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,448 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: volucer-worker
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A Python worker SDK for the volucer worker protocol
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/sailantis/volucer-python-sdk
|
|
7
|
+
Project-URL: Documentation, https://github.com/sailantis/volucer/blob/main/docs/worker-protocol.md
|
|
8
|
+
Project-URL: Specification, https://github.com/sailantis/volucer/blob/main/docs/worker-protocol.md
|
|
9
|
+
Project-URL: Repository, https://github.com/sailantis/volucer-python-sdk
|
|
10
|
+
Project-URL: Issues, https://github.com/sailantis/volucer-python-sdk/issues
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI
|
|
19
|
+
Requires-Python: >=3.10
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# volucer-python-sdk
|
|
25
|
+
|
|
26
|
+
Python bindings for [volucer](https://github.com/sailantis/volucer): the `kv`, `lock` and
|
|
27
|
+
`jobs` services, and the worker protocol.
|
|
28
|
+
|
|
29
|
+
The specification is [`docs/worker-protocol.md`](https://github.com/sailantis/volucer/blob/main/docs/worker-protocol.md)
|
|
30
|
+
in the server repository. This package is the other end of it, beside the PHP one in
|
|
31
|
+
[`sailantis/volucer-php-sdk`](https://github.com/sailantis/volucer-php-sdk). All three
|
|
32
|
+
implement the same document rather than each other, and the wire-format tests in each
|
|
33
|
+
assert the same frozen bytes.
|
|
34
|
+
|
|
35
|
+
## Which half you want
|
|
36
|
+
|
|
37
|
+
There are two ways to reach volucer from Python, and most deployments want the first.
|
|
38
|
+
|
|
39
|
+
**`Rpc` — the services, without changing how your app is served.** You keep gunicorn,
|
|
40
|
+
uvicorn or Granian, keep your container, keep your process model. Your app gains volucer's
|
|
41
|
+
`kv`, `lock` and `jobs` by dialling a socket volucer gives every request:
|
|
42
|
+
|
|
43
|
+
```python
|
|
44
|
+
from volucer_worker import Rpc
|
|
45
|
+
|
|
46
|
+
def application(environ, start_response):
|
|
47
|
+
rpc = Rpc.connect(environ=environ)
|
|
48
|
+
rpc.kv("cache").set("greeting", "hello")
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
That is the whole setup, and it is what the rest of this package is arranged around. See
|
|
52
|
+
[the call plane](#the-call-plane-for-an-application-that-is-not-a-worker).
|
|
53
|
+
|
|
54
|
+
**`Worker` — let volucer serve the app instead of gunicorn.** The application boots once and
|
|
55
|
+
volucer sends it requests over the child's stdin/stdout, so a framework's bootstrap cost stops
|
|
56
|
+
being charged per request. This is worth it only if you want the channel itself: recycling on
|
|
57
|
+
RSS, no HTTP framing on the hot path, one process per slot. If you are happy with gunicorn,
|
|
58
|
+
**use the `upstream` backend instead** — volucer supervises gunicorn over HTTP, needs no SDK at
|
|
59
|
+
all, and is what the plan recommends first.
|
|
60
|
+
|
|
61
|
+
## The call plane, for an application that is not a worker
|
|
62
|
+
|
|
63
|
+
A worker asks for `kv`, `lock` and `jobs` with `CALL` frames on the stream that carries its
|
|
64
|
+
requests. A FastCGI application has no such stream — it exists for the duration of one request
|
|
65
|
+
and can only answer the frame it was handed — so volucer serves the same namespaces on a socket
|
|
66
|
+
of its own, `[rpc]`, which `Rpc` dials:
|
|
67
|
+
|
|
68
|
+
```python
|
|
69
|
+
from volucer_worker import Rpc
|
|
70
|
+
|
|
71
|
+
def application(environ, start_response):
|
|
72
|
+
# `environ` is the WSGI request's, and passing it is not optional — see below.
|
|
73
|
+
rpc = Rpc.connect(environ=environ)
|
|
74
|
+
|
|
75
|
+
rpc.kv("cache").set("greeting", "hello")
|
|
76
|
+
lock_id = rpc.lock().acquire("pdf:create")
|
|
77
|
+
rpc.queue("mail").push("SendEmail", {"to": "a@b"})
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
| Handle | Methods |
|
|
81
|
+
| --- | --- |
|
|
82
|
+
| `Rpc.connect(address?, token?, timeout?, environ?)` | Build one; nothing is dialled until the first call |
|
|
83
|
+
| `rpc.kv(storage)` | `get`, `set`, `set_if_absent`, `has`, `delete`, `ttl`, `clear`, `get_multiple`, `get_many`, `set_multiple`, `serializer` |
|
|
84
|
+
| `rpc.lock()` | `acquire`, `try_acquire`, `release`, `exists`, `holders`, `update_ttl` |
|
|
85
|
+
| `rpc.queue(pipeline)` | `push(task, payload, headers)` |
|
|
86
|
+
| `rpc.call(name, params)` | One raw round trip, for a method with no handle |
|
|
87
|
+
| `rpc.last_error`, `rpc.last_call_was_unknown` | Why the last call failed, and whether it may have taken effect |
|
|
88
|
+
|
|
89
|
+
**Pass `environ` from a WSGI application.** volucer puts the address in the CGI *request*, and the
|
|
90
|
+
process the application runs in only receives `VOLUCER_FCGI_ADDRESS` — so a client reading
|
|
91
|
+
`os.environ` works for a script started by hand and fails for every real request, with a message
|
|
92
|
+
that blames the deployment. `Rpc.connect(environ=environ)` reads the right mapping; a CLI script
|
|
93
|
+
or a worker omits it and gets `os.environ`, which is correct for both.
|
|
94
|
+
|
|
95
|
+
Two things differ from a worker's channel and are worth knowing before relying on one. A call has
|
|
96
|
+
a **deadline** (`Rpc.connect(timeout=…)`, default 10 s), because this reads a socket rather than a
|
|
97
|
+
pipe — and a `lock.acquire` with a long `wait` needs a deadline that covers it, since
|
|
98
|
+
`[rpc].call_timeout_seconds` governs only how long the *server* spends writing an answer.
|
|
99
|
+
`last_call_was_unknown` is `True` only when the call may have been served: a refusal sets it
|
|
100
|
+
`False`, so retrying is a decision rather than a gamble.
|
|
101
|
+
|
|
102
|
+
`Kv` serializes with JSON by default and `serializer(encode, decode)` replaces that. The server
|
|
103
|
+
holds opaque bytes and never sees your objects, which is what lets a value written by a PHP worker
|
|
104
|
+
be read here — and `_decode_value` returns `bytes` rather than raising for anything that is not
|
|
105
|
+
JSON, so one storage can be shared by two languages.
|
|
106
|
+
|
|
107
|
+
## What a worker is
|
|
108
|
+
|
|
109
|
+
Worker mode boots an application once and serves many requests from that process, instead
|
|
110
|
+
of booting it per request the way `php-cgi` and FPM-like deployments do. It is the
|
|
111
|
+
RoadRunner/Swoole/FrankenPHP value proposition, and it is why a real framework's bootstrap
|
|
112
|
+
cost stops being charged on every request.
|
|
113
|
+
|
|
114
|
+
A Python application already has servers that do this — gunicorn, uvicorn, Granian. The
|
|
115
|
+
reason to use this SDK instead is the channel rather than the model: it runs over the
|
|
116
|
+
child's stdin/stdout (or a loopback socket on Windows), so the application keeps its own
|
|
117
|
+
process, its own container and its own warm caches, and volucer supervises it without
|
|
118
|
+
wrapping it in a protocol library first.
|
|
119
|
+
|
|
120
|
+
## Install
|
|
121
|
+
|
|
122
|
+
```console
|
|
123
|
+
pip install volucer-worker
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Or, from a checkout:
|
|
127
|
+
|
|
128
|
+
```console
|
|
129
|
+
pip install git+https://github.com/sailantis/volucer-python-sdk
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Python 3.10 or newer. Nothing is required at runtime beyond the standard library, and there
|
|
133
|
+
are no optional dependencies. A worker SDK loads before an application's own environment is
|
|
134
|
+
known to work, so a dependency here is a failure mode unrelated to the protocol.
|
|
135
|
+
|
|
136
|
+
## A worker, in three lines
|
|
137
|
+
|
|
138
|
+
A plain WSGI application needs no adapter beyond what this package already has:
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
from volucer_worker import Worker, wsgi
|
|
142
|
+
from myapp import application
|
|
143
|
+
|
|
144
|
+
Worker.connect().run(wsgi.call(application))
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
`Worker.connect()` honours `VOLUCER_WORKER_SOCKET` and falls back to stdio. It is the call a
|
|
148
|
+
worker file should make; `Worker.create()` is the explicit-streams form, used when you are
|
|
149
|
+
binding streams yourself — including when the connection was opened by somebody else, which
|
|
150
|
+
is what the `attach` backend needs.
|
|
151
|
+
|
|
152
|
+
The variable carries either form, and `connect()` decides from its prefix:
|
|
153
|
+
|
|
154
|
+
| value | transport |
|
|
155
|
+
| --- | --- |
|
|
156
|
+
| `127.0.0.1:34567` | loopback TCP — the ephemeral port the server bound |
|
|
157
|
+
| `unix:/run/volucer/worker.0.sock` | a unix socket, from `socket = "unix:/run/volucer/worker"` |
|
|
158
|
+
|
|
159
|
+
`volucer_worker.unix_path()` is the whole of the decision and returns `None` for a TCP address,
|
|
160
|
+
so the connection code has one branch. `unix:` is the same convention the server's configuration
|
|
161
|
+
uses for `external`, `attach` and the worker `socket` key, so there is one spelling rather than a
|
|
162
|
+
fourth.
|
|
163
|
+
|
|
164
|
+
## Attaching instead of spawning
|
|
165
|
+
|
|
166
|
+
The `worker` backend starts your process. The `attach` backend does not: it *dials* a relay
|
|
167
|
+
that a supervisor in your own process listens on, and holds one connection per slot. That is
|
|
168
|
+
the shape that lets a supervisor fork its workers after booting the application once, so
|
|
169
|
+
every child inherits the interpreter, the imported modules and the loaded code instead of
|
|
170
|
+
paying for them again.
|
|
171
|
+
|
|
172
|
+
The split matters: **volucer cannot own the fork.** It has to happen in the application's
|
|
173
|
+
process, because the side that owns the listening socket has to be the side that owns the
|
|
174
|
+
fork — and because `os.fork()` in a process that already has threads is not something a
|
|
175
|
+
library can decide safely. So the fork lives in `volucer_worker.supervisor`, and you call it:
|
|
176
|
+
|
|
177
|
+
```python
|
|
178
|
+
# supervisor.py — boot once, then fork
|
|
179
|
+
import django
|
|
180
|
+
django.setup()
|
|
181
|
+
|
|
182
|
+
from django.core.wsgi import get_wsgi_application
|
|
183
|
+
from volucer_worker import supervisor, wsgi
|
|
184
|
+
from myapp import application
|
|
185
|
+
|
|
186
|
+
# Boot before the fork: whatever this closes over is inherited by every child.
|
|
187
|
+
handler = wsgi.call(application)
|
|
188
|
+
|
|
189
|
+
supervisor.serve(None, handler) # or "unix:/run/app/workers.sock"
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
```toml
|
|
193
|
+
[backends.python]
|
|
194
|
+
kind = "attach"
|
|
195
|
+
workers = 16
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
**The address can be written once.** With `None` as the first argument the supervisor reads
|
|
199
|
+
`VOLUCER_RELAY_SOCKET`, and so does the server when `relay` is omitted:
|
|
200
|
+
|
|
201
|
+
```ini
|
|
202
|
+
# the unit file, or a container's environment
|
|
203
|
+
Environment=VOLUCER_RELAY_SOCKET=unix:/run/app/workers.sock
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
That is the counterpart of `VOLUCER_WORKER_SOCKET`, for the mirror-image reason: that one is set
|
|
207
|
+
*by* the server on a child it spawned, so a supervisor cannot read it — no child was spawned. This
|
|
208
|
+
one is set by the operator, and both sides read it. A value passed to `serve()`, or a `relay` key in
|
|
209
|
+
the file, still wins, so a stale variable cannot move a deployment. `supervisor.relay_value()` is
|
|
210
|
+
that resolution on its own.
|
|
211
|
+
|
|
212
|
+
`children` caps how many workers may run at once, and the default (`0`) is **no cap**, which is
|
|
213
|
+
what an `attach` deployment wants: volucer dials `workers` times at startup and holds one
|
|
214
|
+
connection per slot, so the live children are already bounded by that number. A cap **below**
|
|
215
|
+
`workers` is not a queue — the surplus dials sit unaccepted in the listen backlog while the pool
|
|
216
|
+
waits for a handshake no child is there to send.
|
|
217
|
+
|
|
218
|
+
Each child serves exactly one connection and exits. That is what makes recycling cheap — when
|
|
219
|
+
`max_requests` is reached volucer closes the slot, the child sees end-of-file, exits, and the
|
|
220
|
+
supervisor forks a replacement for the next connection. The supervisor reaps its children, so
|
|
221
|
+
a long-lived one does not fill the process table with zombies.
|
|
222
|
+
|
|
223
|
+
**Unix only.** `os.fork()` does not exist on Windows, and `supervisor.serve()` raises there
|
|
224
|
+
rather than silently running a single process. Use `kind = "worker"` or `kind = "upstream"` on
|
|
225
|
+
Windows.
|
|
226
|
+
|
|
227
|
+
**Boot before the fork, connect after it.** A framework, a container and imported modules are
|
|
228
|
+
inherited by every child, which is the saving. An *open connection* must not be: every child
|
|
229
|
+
would inherit the socket and they would take turns reading from it. Open connections lazily,
|
|
230
|
+
per child, on the first request — Django and SQLAlchemy both do this already.
|
|
231
|
+
|
|
232
|
+
### Writing a supervisor yourself
|
|
233
|
+
|
|
234
|
+
`supervisor.serve()` is a convenience, not the contract. What `attach` needs from any
|
|
235
|
+
supervisor is that it serves a connection **it** opened, which is `Worker.create`:
|
|
236
|
+
|
|
237
|
+
```python
|
|
238
|
+
import socket
|
|
239
|
+
|
|
240
|
+
listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
|
|
241
|
+
listener.bind(("127.0.0.1", 9700))
|
|
242
|
+
listener.listen(64)
|
|
243
|
+
|
|
244
|
+
while True:
|
|
245
|
+
connection, _ = listener.accept()
|
|
246
|
+
child = os.fork()
|
|
247
|
+
if child:
|
|
248
|
+
connection.close() # the master must drop its copy
|
|
249
|
+
continue
|
|
250
|
+
listener.close()
|
|
251
|
+
Worker.create( # not connect(): the connection already exists
|
|
252
|
+
connection.makefile("rb", buffering=0),
|
|
253
|
+
connection.makefile("wb", buffering=0),
|
|
254
|
+
).run(handler)
|
|
255
|
+
os._exit(0)
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
The `makefile` calls are not optional — a `socket` has neither `read` nor `write`, which is
|
|
259
|
+
what the worker calls on its streams. Passing the raw socket, as a PHP worker can with its
|
|
260
|
+
file-like streams, fails with `AttributeError`.
|
|
261
|
+
|
|
262
|
+
## Django
|
|
263
|
+
|
|
264
|
+
Django is a WSGI application, so there is nothing to adapt — `get_wsgi_application()` is the
|
|
265
|
+
only Django-specific line:
|
|
266
|
+
|
|
267
|
+
```python
|
|
268
|
+
# worker.py
|
|
269
|
+
import os
|
|
270
|
+
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
|
|
271
|
+
|
|
272
|
+
import django
|
|
273
|
+
django.setup()
|
|
274
|
+
|
|
275
|
+
from django.core.wsgi import get_wsgi_application
|
|
276
|
+
from volucer_worker import Worker, wsgi
|
|
277
|
+
|
|
278
|
+
Worker.connect().run(wsgi.call(get_wsgi_application()))
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
```toml
|
|
282
|
+
[backends.django]
|
|
283
|
+
kind = "worker"
|
|
284
|
+
command = "python worker.py"
|
|
285
|
+
workers = 4
|
|
286
|
+
|
|
287
|
+
[server]
|
|
288
|
+
script_extensions = ["py"] # else /worker.py is PATH_INFO, not a routed script
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
That is the whole integration. `django.setup()` belongs at import time because worker mode
|
|
292
|
+
boots once; `get_wsgi_application()` must be called **after** it, not inside the handler.
|
|
293
|
+
Database connection hygiene needs nothing from you — Django closes old connections on its own
|
|
294
|
+
`request_started`/`request_finished` signals, which its WSGI handler fires per request.
|
|
295
|
+
|
|
296
|
+
Verified against Django 6.1.2 and a real `volucer` binary: routing, `get_host()`,
|
|
297
|
+
`build_absolute_uri()`, sessions in both directions, a cookieless client correctly getting no
|
|
298
|
+
session, and two consecutive database queries.
|
|
299
|
+
|
|
300
|
+
## Flask, FastAPI and everything else WSGI
|
|
301
|
+
|
|
302
|
+
The same four lines. Flask, Bottle and Pyramid expose `app.wsgi_app` / `app` as WSGI callables.
|
|
303
|
+
**FastAPI is ASGI, not WSGI** — see "What this SDK does not do" below.
|
|
304
|
+
|
|
305
|
+
Point a backend at it:
|
|
306
|
+
|
|
307
|
+
```toml
|
|
308
|
+
[backends.python]
|
|
309
|
+
kind = "worker"
|
|
310
|
+
command = "python worker.py"
|
|
311
|
+
workers = 4
|
|
312
|
+
memory_limit_mb = 256
|
|
313
|
+
script_extensions = ["py"]
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
Two configuration keys are not optional for a non-PHP worker:
|
|
317
|
+
|
|
318
|
+
- `script_extensions` must name the extension your entry point has, or `/app.py` arrives at
|
|
319
|
+
the front controller as `PATH_INFO` instead of being routed. A list naming `py` *replaces*
|
|
320
|
+
the default rather than adding to it, so a site serving Python stops treating `.php` as a
|
|
321
|
+
script — which is what "this tree is Python" means.
|
|
322
|
+
- `workers` is the concurrency, because the protocol carries **one request in flight per
|
|
323
|
+
worker process**. That is a deliberate property of the channel rather than a limitation to
|
|
324
|
+
work around: a server with one goroutine or greenlet per request needs a different
|
|
325
|
+
protocol, not a different SDK.
|
|
326
|
+
|
|
327
|
+
## The two Python-specific answers
|
|
328
|
+
|
|
329
|
+
Everything else in this SDK is a transliteration of the specification. These two are not.
|
|
330
|
+
|
|
331
|
+
### stdout is the channel, so the SDK takes it
|
|
332
|
+
|
|
333
|
+
The protocol uses the child's stdout as its channel. PHP solves this with an output buffer
|
|
334
|
+
around `echo`; Python's answer is that importing this package **rebinds `sys.stdout`** to a
|
|
335
|
+
stream that writes to stderr, and keeps the real protocol stream private to the worker.
|
|
336
|
+
|
|
337
|
+
The consequence is worth stating plainly: `print()` still reaches a human (through stderr,
|
|
338
|
+
which the supervisor drains), but it will not appear on the process's own stdout. A worker
|
|
339
|
+
that did not do this would corrupt its framing the first time somebody left a `print` in,
|
|
340
|
+
and the symptom would be a killed worker rather than a stray line.
|
|
341
|
+
|
|
342
|
+
### RSS has no exact per-request answer in Python
|
|
343
|
+
|
|
344
|
+
The server recycles a worker whose reported `peak_memory_bytes` exceeds `memory_limit_mb`,
|
|
345
|
+
and the protocol wants that figure **per request, not per process**: a high-water mark that
|
|
346
|
+
never falls would turn a leak detector into a per-request application boot.
|
|
347
|
+
|
|
348
|
+
PHP has `memory_get_peak_usage()` plus `memory_reset_peak_usage()`, which is exactly the
|
|
349
|
+
right shape. Python does not, so this SDK offers two answers and says which you get:
|
|
350
|
+
|
|
351
|
+
| `track_memory` | Reported figure | Behaviour |
|
|
352
|
+
| --- | --- | --- |
|
|
353
|
+
| `False` (default) | The process's resident set size, from `/proc/self/statm` or `GetProcessMemoryInfo` | Cumulative by nature and **cannot fall**, so a peak that once exceeded the limit recycles the worker after every request. Cheap. |
|
|
354
|
+
| `True` | The peak of Python's own allocator, reset per request via `tracemalloc.reset_peak()` | The shape the protocol asks for, and it excludes memory C extensions allocate outside Python's allocator. Costs a `tracemalloc` hook on every allocation. |
|
|
355
|
+
|
|
356
|
+
```python
|
|
357
|
+
Worker.connect(track_memory=True).run(handler)
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
Use `track_memory=True` if you set `memory_limit_mb` and want it to mean what it says. Use
|
|
361
|
+
the default and **leave `memory_limit_mb` unset** if you want the cheapest worker, because a
|
|
362
|
+
cumulative figure against a threshold recycles constantly rather than detecting a leak.
|
|
363
|
+
Reporting `0` ("this runtime does not report it") is also accepted by the server, and a
|
|
364
|
+
worker that does not report is one the pool never recycles on memory — see
|
|
365
|
+
`Worker.peak_memory_bytes` for where to override it.
|
|
366
|
+
|
|
367
|
+
## The parts of the protocol a handler sees
|
|
368
|
+
|
|
369
|
+
| Frame | Handler surface |
|
|
370
|
+
| --- | --- |
|
|
371
|
+
| `REQUEST` / `RESPONSE` / `BODY` / `END` | `Worker.run(handler)`; the handler returns a `Response`, `bytes`, `str`, a `(status, headers, body)` tuple, or `None` |
|
|
372
|
+
| `JOB` / `ACK` | `Worker.consume(handler)`; `None` acknowledges, `False` requeues, a `str` rejects with a reason, and a raise requeues |
|
|
373
|
+
| `CALL` / `RETURN` | `Worker.call(name, params)` from inside a handler; `Worker.on_call(handler)` answers the server's calls |
|
|
374
|
+
| `LOG` / `METRIC` | `Worker.emit_log(...)`, `Worker.emit_metric(...)` |
|
|
375
|
+
| `CONTROL` | Answered by the SDK; `drain` and `shutdown` stop the loop |
|
|
376
|
+
| `PING` / `PONG` | Answered by the SDK |
|
|
377
|
+
|
|
378
|
+
`Worker.recycle()` asks to be replaced after the current request, which is reported as
|
|
379
|
+
`keep_alive = false` in `END`.
|
|
380
|
+
|
|
381
|
+
## gRPC
|
|
382
|
+
|
|
383
|
+
A gRPC call arrives as an ordinary `REQUEST` whose `content-type` is `application/grpc…`,
|
|
384
|
+
and its outcome travels in the reply's trailer section rather than in the HTTP status. The
|
|
385
|
+
SDK exposes that as `volucer_worker.grpc`:
|
|
386
|
+
|
|
387
|
+
```python
|
|
388
|
+
from volucer_worker import Worker, grpc
|
|
389
|
+
|
|
390
|
+
worker = Worker.connect()
|
|
391
|
+
worker.on_grpc(lambda request, worker: grpc.GrpcResponse.message(encode_reply(request)))
|
|
392
|
+
worker.run(handler)
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
`grpc.GrpcResponse.message(payload)` takes the **framed bytes** — the compression flag and
|
|
396
|
+
the big-endian length included. This SDK does not ship a protobuf encoder, because doing so
|
|
397
|
+
would put a schema in the transport.
|
|
398
|
+
|
|
399
|
+
## Tests
|
|
400
|
+
|
|
401
|
+
```console
|
|
402
|
+
python -m unittest discover -s tests
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
The wire-format tests assert the same frozen bytes as
|
|
406
|
+
`crates/volucer-worker/tests/wire_format.rs` and `volucer-php-sdk/tests/WireFormatTest.php`,
|
|
407
|
+
so all three cannot drift apart silently.
|
|
408
|
+
|
|
409
|
+
`tests/test_rpc.py` drives `Rpc` over a `socket.socketpair`, and asserts on the **bytes the client
|
|
410
|
+
writes** — a batch key is base64, a value is its JSON encoding and then base64, a push carries its
|
|
411
|
+
task. The server's half of that contract is
|
|
412
|
+
`a_batch_key_is_base64_in_both_directions` in the Rust suite, and the two disagreed for three
|
|
413
|
+
releases because neither side had a test for the batch methods.
|
|
414
|
+
|
|
415
|
+
The end-to-end test drives a real `volucer` binary and is skipped unless one is found:
|
|
416
|
+
|
|
417
|
+
```console
|
|
418
|
+
VOLUCER_BIN=/path/to/volucer python -m unittest tests.test_end_to_end
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
It looks for `../volucer/target/debug/volucer` when `VOLUCER_BIN` is unset, so a developer
|
|
422
|
+
working in the sibling checkout needs no environment at all. CI sets `VOLUCER_BIN` and
|
|
423
|
+
fails on a skip, for the reason the server's own suites do: a skipped test and a passing one
|
|
424
|
+
are the same green.
|
|
425
|
+
|
|
426
|
+
## What this SDK does not do
|
|
427
|
+
|
|
428
|
+
- **ASGI.** Concurrency inside one worker needs multiplexed requests on one channel, which
|
|
429
|
+
is a protocol change rather than an adapter. Do not expect it in this release.
|
|
430
|
+
- **Streaming responses.** `RESPONSE` declares `body_len` before the body, so a response is
|
|
431
|
+
complete before it starts. That is a protocol property, not a missing feature here.
|
|
432
|
+
- **Per-request state reset for your framework.** WSGI's per-request environment is rebuilt
|
|
433
|
+
by the SDK, so that much is reset; a framework that keeps module-level state, an open
|
|
434
|
+
database connection or a cached container has to deal with that itself. **Django does not
|
|
435
|
+
need anything extra**: `django/db/__init__.py` connects `close_old_connections` to both
|
|
436
|
+
`request_started` and `request_finished`, and `WSGIHandler` fires both, so a transaction left
|
|
437
|
+
open by one view is closed before the next one runs — verified against a real `volucer`
|
|
438
|
+
binary by making a view abandon a transaction on purpose. The check that matters is two
|
|
439
|
+
consecutive requests that must not see each other's state, and
|
|
440
|
+
`tests/test_end_to_end.py` asserts exactly that for the SDK's own surface.
|
|
441
|
+
- **Forking on Windows.** `supervisor.serve()` needs `os.fork()`. The platform without it is
|
|
442
|
+
served by `kind = "worker"` or `kind = "upstream"`, and the end-to-end suite proves the
|
|
443
|
+
`attach` contract on Windows with a threaded supervisor instead.
|
|
444
|
+
|
|
445
|
+
`Rpc` is the one part that does not need the worker channel at all — see
|
|
446
|
+
[the call plane](#the-call-plane-for-an-application-that-is-not-a-worker), which is the option to
|
|
447
|
+
reach for when `upstream` is the right deployment shape but the application still needs a cache
|
|
448
|
+
and a lock.
|