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.
@@ -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.