pydistlock 0.2.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.
- pydistlock-0.2.0/Cargo.toml +16 -0
- pydistlock-0.2.0/PKG-INFO +258 -0
- pydistlock-0.2.0/README.md +241 -0
- pydistlock-0.2.0/crates/distlock-client/Cargo.toml +31 -0
- pydistlock-0.2.0/crates/distlock-client/README.md +52 -0
- pydistlock-0.2.0/crates/distlock-client/src/blocking.rs +161 -0
- pydistlock-0.2.0/crates/distlock-client/src/client.rs +1507 -0
- pydistlock-0.2.0/crates/distlock-client/src/conn.rs +217 -0
- pydistlock-0.2.0/crates/distlock-client/src/error.rs +96 -0
- pydistlock-0.2.0/crates/distlock-client/src/event.rs +153 -0
- pydistlock-0.2.0/crates/distlock-client/src/lib.rs +46 -0
- pydistlock-0.2.0/crates/distlock-client/src/lock.rs +331 -0
- pydistlock-0.2.0/crates/distlock-client/src/maintenance.rs +85 -0
- pydistlock-0.2.0/crates/distlock-client/tests/blocking.rs +73 -0
- pydistlock-0.2.0/crates/distlock-client/tests/client.rs +637 -0
- pydistlock-0.2.0/crates/distlock-client/tests/common/mod.rs +328 -0
- pydistlock-0.2.0/crates/distlock-client/tests/events.rs +550 -0
- pydistlock-0.2.0/crates/distlock-client/tests/maintenance.rs +185 -0
- pydistlock-0.2.0/crates/distlock-client/tests/resilience.rs +231 -0
- pydistlock-0.2.0/crates/distlock-proto/Cargo.toml +20 -0
- pydistlock-0.2.0/crates/distlock-proto/README.md +23 -0
- pydistlock-0.2.0/crates/distlock-proto/build.rs +9 -0
- pydistlock-0.2.0/crates/distlock-proto/proto/distlock/v1/distlock.proto +357 -0
- pydistlock-0.2.0/crates/distlock-proto/src/lib.rs +107 -0
- pydistlock-0.2.0/distlock/__init__.py +61 -0
- pydistlock-0.2.0/distlock/_native.pyi +109 -0
- pydistlock-0.2.0/distlock/client.py +258 -0
- pydistlock-0.2.0/distlock/enums.py +45 -0
- pydistlock-0.2.0/distlock/errors.py +95 -0
- pydistlock-0.2.0/distlock/event.py +173 -0
- pydistlock-0.2.0/distlock/lock.py +353 -0
- pydistlock-0.2.0/distlock/maintenance.py +72 -0
- pydistlock-0.2.0/distlock/py.typed +0 -0
- pydistlock-0.2.0/distlock/settings.py +120 -0
- pydistlock-0.2.0/pyproject.toml +34 -0
- pydistlock-0.2.0/python/Cargo.lock +760 -0
- pydistlock-0.2.0/python/Cargo.toml +23 -0
- pydistlock-0.2.0/python/README.md +241 -0
- pydistlock-0.2.0/python/src/lib.rs +661 -0
- pydistlock-0.2.0/python/tests/conftest.py +185 -0
- pydistlock-0.2.0/python/tests/test_events.py +299 -0
- pydistlock-0.2.0/python/tests/test_locks.py +462 -0
- pydistlock-0.2.0/python/tests/test_maintenance.py +163 -0
- pydistlock-0.2.0/python/tests/test_resilience.py +199 -0
- pydistlock-0.2.0/python/tests/test_settings.py +156 -0
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
[workspace]
|
|
2
|
+
resolver = "3"
|
|
3
|
+
members = ["crates/*"]
|
|
4
|
+
# `python/` is built by maturin and needs a Python interpreter, so it is its own workspace.
|
|
5
|
+
exclude = ["python"]
|
|
6
|
+
|
|
7
|
+
[workspace.package]
|
|
8
|
+
version = "0.2.0"
|
|
9
|
+
edition = "2024"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
repository = "https://github.com/loggerheads-with-binary/distlock"
|
|
12
|
+
keywords = ["lock", "distributed", "mutex", "lease", "semaphore"]
|
|
13
|
+
categories = ["concurrency", "network-programming"]
|
|
14
|
+
|
|
15
|
+
[workspace.lints.rust]
|
|
16
|
+
unsafe_code = "forbid"
|
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pydistlock
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Classifier: Programming Language :: Python :: 3
|
|
5
|
+
Classifier: Programming Language :: Rust
|
|
6
|
+
Classifier: Typing :: Typed
|
|
7
|
+
Requires-Dist: pydantic>=2.5,<3
|
|
8
|
+
Requires-Dist: pytest>=8 ; extra == 'dev'
|
|
9
|
+
Requires-Dist: maturin>=1.7,<2.0 ; extra == 'dev'
|
|
10
|
+
Provides-Extra: dev
|
|
11
|
+
Summary: Distributed locks (mutex, read/write, semaphore) with leases, on top of a Rust client
|
|
12
|
+
License: MIT
|
|
13
|
+
Requires-Python: >=3.9
|
|
14
|
+
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
|
|
15
|
+
Project-URL: Repository, https://github.com/loggerheads-with-binary/distlock
|
|
16
|
+
|
|
17
|
+
# pydistlock
|
|
18
|
+
|
|
19
|
+
[](https://github.com/loggerheads-with-binary/distlock/actions/workflows/ci.yml)
|
|
20
|
+
[](https://github.com/loggerheads-with-binary/distlock/actions/workflows/release.yml)
|
|
21
|
+
[](https://codecov.io/gh/loggerheads-with-binary/distlock)
|
|
22
|
+
[](https://pypi.org/project/pydistlock/)
|
|
23
|
+
[](https://pypi.org/project/pydistlock/)
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pip install pydistlock # imports as `distlock`
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The client for the [distlock](https://github.com/loggerheads-with-binary/distlock) server.
|
|
30
|
+
Distributed locks for Python: mutexes, read/write locks and semaphores, with leases that renew
|
|
31
|
+
themselves, on top of the Rust client in `crates/distlock-client`. Async and blocking, one API.
|
|
32
|
+
|
|
33
|
+
```python
|
|
34
|
+
from distlock import DistLockClient, ProcessingStatus
|
|
35
|
+
|
|
36
|
+
client = DistLockClient.from_url(
|
|
37
|
+
"distlock://billing:s3cret@10.0.0.5:7878/billing?pool_size=5&default_ttl=30"
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
async with client.mutex("nightly-report") as guard:
|
|
41
|
+
if guard.status is ProcessingStatus.SUCCEEDED:
|
|
42
|
+
return # the previous holder already did the work
|
|
43
|
+
... # the lease is renewed for you while this runs
|
|
44
|
+
guard.set_status(ProcessingStatus.SUCCEEDED) # recorded when the block ends
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Build from source
|
|
48
|
+
|
|
49
|
+
The package is a PyO3 extension (`distlock._native`, built with [maturin](https://www.maturin.rs))
|
|
50
|
+
plus a pure-Python layer. One `abi3` wheel serves Python 3.9 and newer.
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
cd python
|
|
54
|
+
python -m venv .venv && source .venv/bin/activate
|
|
55
|
+
pip install maturin pytest "pydantic>=2.5"
|
|
56
|
+
maturin develop # builds the Rust code and installs the package, editable
|
|
57
|
+
cargo build -p distlock-server # the tests start the real server (from the repo root: ../target/debug)
|
|
58
|
+
pytest
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`maturin build --release` makes a wheel. Only `pydantic` is needed at runtime. The tests need
|
|
62
|
+
`htpasswd` (macOS has it; `apache2-utils` elsewhere) to create a users file with the repo's
|
|
63
|
+
`scripts/hash-password.sh`; set `DISTLOCK_SERVER_BIN` to use a server binary from elsewhere.
|
|
64
|
+
|
|
65
|
+
## Connecting
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
client = DistLockClient.from_url("distlock://client_id:password@host:port/namespace?pool_size=5&tls=false&default_ttl=30")
|
|
69
|
+
client = DistLockClient.from_env() # reads $DISTLOCK_URL
|
|
70
|
+
client = DistLockClient(client_id="billing", password="s3cret", host="10.0.0.5", namespace="billing")
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
| URL part | Meaning | Default |
|
|
74
|
+
|---|---|---|
|
|
75
|
+
| `client_id:password` | a user from the server's users file (percent-encode `@ : / %`) | required |
|
|
76
|
+
| `host`, `port` | the server | port `7878` |
|
|
77
|
+
| `/namespace` | prefix for every lock name (`namespace:...`), to keep applications apart | none |
|
|
78
|
+
| `pool_size` | TCP connections (1–256); they all share one session | `4` |
|
|
79
|
+
| `default_ttl` | lease length in seconds for locks that do not set `ttl` | `30` |
|
|
80
|
+
| `tls` | not supported by the server yet; `true` raises `ConfigError` | `false` |
|
|
81
|
+
|
|
82
|
+
URLs are parsed with `urllib` and validated with pydantic ([`ClientSettings`](https://github.com/loggerheads-with-binary/distlock/blob/main/python/distlock/settings.py));
|
|
83
|
+
mistakes raise `ConfigError` with a message that never contains the password.
|
|
84
|
+
|
|
85
|
+
Creating a client does no I/O. The pool connects the first time a lock is acquired (or on
|
|
86
|
+
`await client.connect()`, to fail fast on bad credentials). The server assigns a **session id**
|
|
87
|
+
when the pool is set up, visible as `client.session_id`; all connections of the pool share it, so any
|
|
88
|
+
connection can carry any request, and a dropped connection is re-established and the session
|
|
89
|
+
re-joined without losing locks.
|
|
90
|
+
|
|
91
|
+
## Locks
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
lock = client.lock("name", ttl=None, namespace=None, mode=LockMode.WRITE, wait=None)
|
|
95
|
+
|
|
96
|
+
client.rlock("name") # shared: many readers at once, never alongside a writer
|
|
97
|
+
client.wlock("name") # exclusive: blocks and is blocked by every reader and writer of that name
|
|
98
|
+
client.mutex("name") # exclusive, in its own space: a mutex "x" and an rlock/wlock "x" do not conflict
|
|
99
|
+
client.semaphore("name", capacity=5, permits=1)
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
* `ttl` is the lease length in seconds (default: the client's `default_ttl`). It is **renewed in the
|
|
103
|
+
background** for as long as you hold the lock, so it is a liveness bound, not a time limit on your work.
|
|
104
|
+
* `wait` is how long acquiring may wait: `None` (default) as long as the server allows, `0` not at all,
|
|
105
|
+
otherwise `LockTimeout` after that many seconds.
|
|
106
|
+
* A `Lock` is a reusable definition. Enter it as many times as you like, from as many tasks or threads
|
|
107
|
+
as you like; each entry gets its own grant and its own `LockGuard`.
|
|
108
|
+
* Read and write locks are fair (FIFO): a waiting writer is not starved by later readers.
|
|
109
|
+
* A semaphore's first acquirer defines its capacity; it disappears when its last holder and waiter are gone.
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
async with lock as guard: ... # or: with lock as guard: ... (blocking)
|
|
113
|
+
guard = await lock.acquire(wait=5) # raises LockTimeout; guard.release() when done
|
|
114
|
+
guard = await lock.try_acquire() # None if taken right now
|
|
115
|
+
guard = lock.acquire_sync() / lock.try_acquire_sync()
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Cancellation is safe: cancelling a waiting `acquire` (a `wait_for` timeout, a cancelled task) withdraws
|
|
119
|
+
the request from the server, so it can never be granted to nobody; Ctrl-C interrupts a blocking acquire the same way.
|
|
120
|
+
|
|
121
|
+
## Events
|
|
122
|
+
|
|
123
|
+
A named broadcast, like `asyncio.Event` with a limited memory: many clients wait, one sets, and the set says how many it woke.
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
event = client.event("deploy-finished") # also spelled client.Event(...)
|
|
127
|
+
value = await event.wait(timeout=60) # the setter's value, or None; LockTimeout after 60 s
|
|
128
|
+
|
|
129
|
+
woken = await client.event("deploy-finished").set("v1.2.3")
|
|
130
|
+
assert woken == number_of_clients_waiting_right_now
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
* `set(value=None, *, publish_for=None)`: **publish window.** For `publish_for` seconds after a set, the event counts as
|
|
134
|
+
*published*: a wait that starts in that window returns at once with the same value. After it the event is gone and waiters
|
|
135
|
+
wait for the next set. `None` uses the server's default (10 s), `0` wakes only the clients already waiting, and long windows
|
|
136
|
+
are capped by the server.
|
|
137
|
+
* `wait(timeout=None)`: `None` waits as long as the server allows, `0` only checks whether the event is published right now,
|
|
138
|
+
anything else raises `LockTimeout` (a `TimeoutError`) when it runs out. Cancelling the task or pressing Ctrl-C withdraws the wait.
|
|
139
|
+
* An `Event` object remembers the last publication its `wait()` returned and only returns newer ones, so a loop on one object
|
|
140
|
+
does not spin while a publication is still inside its window:
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
event = client.event("tick")
|
|
144
|
+
while True:
|
|
145
|
+
value = await event.wait() # never the same publication twice
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Use a fresh `Event`, `event.reset()` or `wait(after=...)` to see an earlier publication again; `event.last_id` is the id of
|
|
149
|
+
the last one returned.
|
|
150
|
+
* Blocking forms: `wait_sync()` and `set_sync()`.
|
|
151
|
+
* Events are separate from locks: an event and a lock with the same name do not interact. Namespaces apply as for locks.
|
|
152
|
+
* **Delivery.** A wait survives dropped connections. A set made while this client is disconnected cannot be delivered then,
|
|
153
|
+
but the client asks again after it reconnects and is answered from the publish window, so use a window longer than a
|
|
154
|
+
reconnect (the server default is 10 s) for events that must not be missed. With `publish_for=0` a wake-up lost that way is gone.
|
|
155
|
+
A `set` is never retried: if its connection fails, `ConnectionFailed` is raised and whether it took effect is unknown.
|
|
156
|
+
|
|
157
|
+
## The guard
|
|
158
|
+
|
|
159
|
+
| | |
|
|
160
|
+
|---|---|
|
|
161
|
+
| `guard.status` | the previous holder's `ProcessingStatus` (`SUCCEEDED`, `FAILED`, `STORED`, or `ABANDONED`), else `None` |
|
|
162
|
+
| `guard.previous` | the same with `set_by_token` and `age` |
|
|
163
|
+
| `guard.set_status(status, ttl=None)` | leave your outcome for the next holder; applied when the block ends |
|
|
164
|
+
| `guard.fencing_token` | strictly increasing across all grants; hand it to what you protect and reject older ones |
|
|
165
|
+
| `guard.lost` / `guard.check()` / `await guard.wait_lost()` | has the lease been lost? |
|
|
166
|
+
| `await guard.release()` / `guard.release_sync()` | release early (idempotent) |
|
|
167
|
+
| `await guard.extend(ttl)` | lengthen the lease beyond what renewal gives you (rarely needed) |
|
|
168
|
+
|
|
169
|
+
Statuses: only **mutex and write** holders can set one (`InvalidArgument` otherwise); readers and
|
|
170
|
+
semaphore holders can read it. Releasing without `set_status` leaves the previous status untouched.
|
|
171
|
+
`ABANDONED` is assigned by the server when a holder's lease expired, or its session ended, while it
|
|
172
|
+
still held the lock; you can read it but not set it. A status stays readable for the server's
|
|
173
|
+
`state_ttl` (10 minutes by default; `set_status(..., ttl=...)` overrides it).
|
|
174
|
+
|
|
175
|
+
If the lease is lost while you hold the lock (the server restarted, a long network partition), `guard.lost`
|
|
176
|
+
turns true, and leaving the block raises `LockLost` (unless another exception is already propagating, which
|
|
177
|
+
is never masked). Call `guard.check()` before irreversible steps of a long job.
|
|
178
|
+
|
|
179
|
+
## Errors
|
|
180
|
+
|
|
181
|
+
Everything derives from `DistLockError`. Where a standard exception fits, it is also that:
|
|
182
|
+
`LockTimeout` is a `TimeoutError`, `ConnectionFailed` a `ConnectionError`, `InvalidArgument`/`ConfigError` a `ValueError`.
|
|
183
|
+
|
|
184
|
+
| exception | when |
|
|
185
|
+
|---|---|
|
|
186
|
+
| `ConfigError` | bad URL or settings |
|
|
187
|
+
| `AuthenticationError` | wrong client id / password |
|
|
188
|
+
| `ConnectionFailed` | server unreachable or not ready (the pool keeps retrying in the background) |
|
|
189
|
+
| `LockTimeout` / `LockBusy` | waited out (a lock not obtained, or an event not set, in time) / `wait=0` and it was taken |
|
|
190
|
+
| `LockLost` | the lease expired before release |
|
|
191
|
+
| `MaintenanceError` | a maintenance command could not be carried out; nothing changed |
|
|
192
|
+
| `SessionLost` | the server forgot the session; the client logs in again by itself, but old locks are gone |
|
|
193
|
+
| `ClientClosed` | the client was closed |
|
|
194
|
+
| `InvalidArgument` / `ServerError` | rejected argument / anything else the server reports |
|
|
195
|
+
|
|
196
|
+
## Staying alive
|
|
197
|
+
|
|
198
|
+
* **Leases renew themselves** for as long as a guard is held: every `ttl / 3` the Rust client sends a lease extension, on its
|
|
199
|
+
own threads. That is independent of Python, so a blocked event loop (`time.sleep` in async code), a CPU-bound loop holding the
|
|
200
|
+
GIL, or a client object that went out of scope cannot make a lease lapse. Each renewal attempt is bounded and retried on
|
|
201
|
+
another connection, so one hung connection cannot eat a lease either.
|
|
202
|
+
* **Heartbeats keep the pool's connections up.** Every connection pings the server at half the server's `ping_interval`
|
|
203
|
+
(default 10 s). A connection that hears nothing for a full interval is considered dead and replaced, and TCP keepalive
|
|
204
|
+
backs this up at the OS level.
|
|
205
|
+
* **The pool repairs itself.** Dropped connections are re-established with jittered backoff, rejoining the same session (your
|
|
206
|
+
locks are re-verified against the server's view); if the server forgot the session (a restart), the client logs in again and
|
|
207
|
+
any locks held through the old session report `lost`.
|
|
208
|
+
|
|
209
|
+
```python
|
|
210
|
+
client.connections # pool connections up right now
|
|
211
|
+
client.reconnects # connections re-established since the start
|
|
212
|
+
await client.ping() # round-trip time to the server, in seconds (client.ping_sync() when blocking)
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
If every connection is down for more than ten seconds, calls raise `AuthenticationError` when the server refuses the credentials
|
|
216
|
+
on re-login (a rotated password), and `ConnectionFailed` (with the underlying reason) otherwise.
|
|
217
|
+
|
|
218
|
+
## Maintenance
|
|
219
|
+
|
|
220
|
+
```python
|
|
221
|
+
report = await client.maintenance.reset_users() # or client.maintenance.reset_users_sync()
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
Tells the server to re-read its users file (`DISTLOCK_USERS_FILE`) and swap it in. Logins are never refused or delayed while this
|
|
225
|
+
happens (the server swaps an immutable snapshot atomically). Users that are **gone from the file or now disabled are thrown
|
|
226
|
+
out**: their sessions end, their locks are released (the next holder sees `ABANDONED`, after the server's lock-delay) and the
|
|
227
|
+
server closes **every one of their TCP connections**, including yours if you removed yourself: you still get the report, with
|
|
228
|
+
`report.invoker_dropped` set, and after that your calls raise `AuthenticationError` until the user is added back, which this
|
|
229
|
+
client then notices by itself. Users added or re-enabled can log in; a changed password applies to new logins only.
|
|
230
|
+
|
|
231
|
+
| `ResetUsersReport` | |
|
|
232
|
+
|---|---|
|
|
233
|
+
| `added`, `removed`, `disabled`, `enabled`, `password_changed` | counts of users in each category (names are in the server log, not in the reply) |
|
|
234
|
+
| `sessions_closed`, `connections_closed` | what was thrown out |
|
|
235
|
+
| `invoker_dropped` | you were among them |
|
|
236
|
+
| `unchanged` | nothing at all changed |
|
|
237
|
+
|
|
238
|
+
If the file cannot be loaded you get `MaintenanceError`, nothing changes, and the old users stay in force. Calling it again is
|
|
239
|
+
always safe. There is no authorization beyond being logged in yet, so any client can send it; it can only make the server
|
|
240
|
+
re-read a file the administrator controls.
|
|
241
|
+
|
|
242
|
+
## Lifecycle
|
|
243
|
+
|
|
244
|
+
```python
|
|
245
|
+
async with DistLockClient.from_url(url) as client: # connects now; on exit ends the session
|
|
246
|
+
... # (the server releases every lock it still holds)
|
|
247
|
+
client.close_sync() # or: await client.close()
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Dropping the last reference to a guard releases its lock (without a status); a client that is simply
|
|
251
|
+
dropped stops its pool and leaves its session to expire on the server.
|
|
252
|
+
|
|
253
|
+
## Names on the wire
|
|
254
|
+
|
|
255
|
+
The server sees `namespace:family:name` with `family` one of `mutex`, `rw`, `sem`, or `event`. That is how a mutex
|
|
256
|
+
and a read/write lock with the same name stay separate, and how namespaces keep applications apart.
|
|
257
|
+
`:` is therefore not allowed in a namespace (it is fine inside a lock name).
|
|
258
|
+
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
# pydistlock
|
|
2
|
+
|
|
3
|
+
[](https://github.com/loggerheads-with-binary/distlock/actions/workflows/ci.yml)
|
|
4
|
+
[](https://github.com/loggerheads-with-binary/distlock/actions/workflows/release.yml)
|
|
5
|
+
[](https://codecov.io/gh/loggerheads-with-binary/distlock)
|
|
6
|
+
[](https://pypi.org/project/pydistlock/)
|
|
7
|
+
[](https://pypi.org/project/pydistlock/)
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pip install pydistlock # imports as `distlock`
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
The client for the [distlock](https://github.com/loggerheads-with-binary/distlock) server.
|
|
14
|
+
Distributed locks for Python: mutexes, read/write locks and semaphores, with leases that renew
|
|
15
|
+
themselves, on top of the Rust client in `crates/distlock-client`. Async and blocking, one API.
|
|
16
|
+
|
|
17
|
+
```python
|
|
18
|
+
from distlock import DistLockClient, ProcessingStatus
|
|
19
|
+
|
|
20
|
+
client = DistLockClient.from_url(
|
|
21
|
+
"distlock://billing:s3cret@10.0.0.5:7878/billing?pool_size=5&default_ttl=30"
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
async with client.mutex("nightly-report") as guard:
|
|
25
|
+
if guard.status is ProcessingStatus.SUCCEEDED:
|
|
26
|
+
return # the previous holder already did the work
|
|
27
|
+
... # the lease is renewed for you while this runs
|
|
28
|
+
guard.set_status(ProcessingStatus.SUCCEEDED) # recorded when the block ends
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Build from source
|
|
32
|
+
|
|
33
|
+
The package is a PyO3 extension (`distlock._native`, built with [maturin](https://www.maturin.rs))
|
|
34
|
+
plus a pure-Python layer. One `abi3` wheel serves Python 3.9 and newer.
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
cd python
|
|
38
|
+
python -m venv .venv && source .venv/bin/activate
|
|
39
|
+
pip install maturin pytest "pydantic>=2.5"
|
|
40
|
+
maturin develop # builds the Rust code and installs the package, editable
|
|
41
|
+
cargo build -p distlock-server # the tests start the real server (from the repo root: ../target/debug)
|
|
42
|
+
pytest
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
`maturin build --release` makes a wheel. Only `pydantic` is needed at runtime. The tests need
|
|
46
|
+
`htpasswd` (macOS has it; `apache2-utils` elsewhere) to create a users file with the repo's
|
|
47
|
+
`scripts/hash-password.sh`; set `DISTLOCK_SERVER_BIN` to use a server binary from elsewhere.
|
|
48
|
+
|
|
49
|
+
## Connecting
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
client = DistLockClient.from_url("distlock://client_id:password@host:port/namespace?pool_size=5&tls=false&default_ttl=30")
|
|
53
|
+
client = DistLockClient.from_env() # reads $DISTLOCK_URL
|
|
54
|
+
client = DistLockClient(client_id="billing", password="s3cret", host="10.0.0.5", namespace="billing")
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
| URL part | Meaning | Default |
|
|
58
|
+
|---|---|---|
|
|
59
|
+
| `client_id:password` | a user from the server's users file (percent-encode `@ : / %`) | required |
|
|
60
|
+
| `host`, `port` | the server | port `7878` |
|
|
61
|
+
| `/namespace` | prefix for every lock name (`namespace:...`), to keep applications apart | none |
|
|
62
|
+
| `pool_size` | TCP connections (1–256); they all share one session | `4` |
|
|
63
|
+
| `default_ttl` | lease length in seconds for locks that do not set `ttl` | `30` |
|
|
64
|
+
| `tls` | not supported by the server yet; `true` raises `ConfigError` | `false` |
|
|
65
|
+
|
|
66
|
+
URLs are parsed with `urllib` and validated with pydantic ([`ClientSettings`](https://github.com/loggerheads-with-binary/distlock/blob/main/python/distlock/settings.py));
|
|
67
|
+
mistakes raise `ConfigError` with a message that never contains the password.
|
|
68
|
+
|
|
69
|
+
Creating a client does no I/O. The pool connects the first time a lock is acquired (or on
|
|
70
|
+
`await client.connect()`, to fail fast on bad credentials). The server assigns a **session id**
|
|
71
|
+
when the pool is set up, visible as `client.session_id`; all connections of the pool share it, so any
|
|
72
|
+
connection can carry any request, and a dropped connection is re-established and the session
|
|
73
|
+
re-joined without losing locks.
|
|
74
|
+
|
|
75
|
+
## Locks
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
lock = client.lock("name", ttl=None, namespace=None, mode=LockMode.WRITE, wait=None)
|
|
79
|
+
|
|
80
|
+
client.rlock("name") # shared: many readers at once, never alongside a writer
|
|
81
|
+
client.wlock("name") # exclusive: blocks and is blocked by every reader and writer of that name
|
|
82
|
+
client.mutex("name") # exclusive, in its own space: a mutex "x" and an rlock/wlock "x" do not conflict
|
|
83
|
+
client.semaphore("name", capacity=5, permits=1)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
* `ttl` is the lease length in seconds (default: the client's `default_ttl`). It is **renewed in the
|
|
87
|
+
background** for as long as you hold the lock, so it is a liveness bound, not a time limit on your work.
|
|
88
|
+
* `wait` is how long acquiring may wait: `None` (default) as long as the server allows, `0` not at all,
|
|
89
|
+
otherwise `LockTimeout` after that many seconds.
|
|
90
|
+
* A `Lock` is a reusable definition. Enter it as many times as you like, from as many tasks or threads
|
|
91
|
+
as you like; each entry gets its own grant and its own `LockGuard`.
|
|
92
|
+
* Read and write locks are fair (FIFO): a waiting writer is not starved by later readers.
|
|
93
|
+
* A semaphore's first acquirer defines its capacity; it disappears when its last holder and waiter are gone.
|
|
94
|
+
|
|
95
|
+
```python
|
|
96
|
+
async with lock as guard: ... # or: with lock as guard: ... (blocking)
|
|
97
|
+
guard = await lock.acquire(wait=5) # raises LockTimeout; guard.release() when done
|
|
98
|
+
guard = await lock.try_acquire() # None if taken right now
|
|
99
|
+
guard = lock.acquire_sync() / lock.try_acquire_sync()
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Cancellation is safe: cancelling a waiting `acquire` (a `wait_for` timeout, a cancelled task) withdraws
|
|
103
|
+
the request from the server, so it can never be granted to nobody; Ctrl-C interrupts a blocking acquire the same way.
|
|
104
|
+
|
|
105
|
+
## Events
|
|
106
|
+
|
|
107
|
+
A named broadcast, like `asyncio.Event` with a limited memory: many clients wait, one sets, and the set says how many it woke.
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
event = client.event("deploy-finished") # also spelled client.Event(...)
|
|
111
|
+
value = await event.wait(timeout=60) # the setter's value, or None; LockTimeout after 60 s
|
|
112
|
+
|
|
113
|
+
woken = await client.event("deploy-finished").set("v1.2.3")
|
|
114
|
+
assert woken == number_of_clients_waiting_right_now
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
* `set(value=None, *, publish_for=None)`: **publish window.** For `publish_for` seconds after a set, the event counts as
|
|
118
|
+
*published*: a wait that starts in that window returns at once with the same value. After it the event is gone and waiters
|
|
119
|
+
wait for the next set. `None` uses the server's default (10 s), `0` wakes only the clients already waiting, and long windows
|
|
120
|
+
are capped by the server.
|
|
121
|
+
* `wait(timeout=None)`: `None` waits as long as the server allows, `0` only checks whether the event is published right now,
|
|
122
|
+
anything else raises `LockTimeout` (a `TimeoutError`) when it runs out. Cancelling the task or pressing Ctrl-C withdraws the wait.
|
|
123
|
+
* An `Event` object remembers the last publication its `wait()` returned and only returns newer ones, so a loop on one object
|
|
124
|
+
does not spin while a publication is still inside its window:
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
event = client.event("tick")
|
|
128
|
+
while True:
|
|
129
|
+
value = await event.wait() # never the same publication twice
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Use a fresh `Event`, `event.reset()` or `wait(after=...)` to see an earlier publication again; `event.last_id` is the id of
|
|
133
|
+
the last one returned.
|
|
134
|
+
* Blocking forms: `wait_sync()` and `set_sync()`.
|
|
135
|
+
* Events are separate from locks: an event and a lock with the same name do not interact. Namespaces apply as for locks.
|
|
136
|
+
* **Delivery.** A wait survives dropped connections. A set made while this client is disconnected cannot be delivered then,
|
|
137
|
+
but the client asks again after it reconnects and is answered from the publish window, so use a window longer than a
|
|
138
|
+
reconnect (the server default is 10 s) for events that must not be missed. With `publish_for=0` a wake-up lost that way is gone.
|
|
139
|
+
A `set` is never retried: if its connection fails, `ConnectionFailed` is raised and whether it took effect is unknown.
|
|
140
|
+
|
|
141
|
+
## The guard
|
|
142
|
+
|
|
143
|
+
| | |
|
|
144
|
+
|---|---|
|
|
145
|
+
| `guard.status` | the previous holder's `ProcessingStatus` (`SUCCEEDED`, `FAILED`, `STORED`, or `ABANDONED`), else `None` |
|
|
146
|
+
| `guard.previous` | the same with `set_by_token` and `age` |
|
|
147
|
+
| `guard.set_status(status, ttl=None)` | leave your outcome for the next holder; applied when the block ends |
|
|
148
|
+
| `guard.fencing_token` | strictly increasing across all grants; hand it to what you protect and reject older ones |
|
|
149
|
+
| `guard.lost` / `guard.check()` / `await guard.wait_lost()` | has the lease been lost? |
|
|
150
|
+
| `await guard.release()` / `guard.release_sync()` | release early (idempotent) |
|
|
151
|
+
| `await guard.extend(ttl)` | lengthen the lease beyond what renewal gives you (rarely needed) |
|
|
152
|
+
|
|
153
|
+
Statuses: only **mutex and write** holders can set one (`InvalidArgument` otherwise); readers and
|
|
154
|
+
semaphore holders can read it. Releasing without `set_status` leaves the previous status untouched.
|
|
155
|
+
`ABANDONED` is assigned by the server when a holder's lease expired, or its session ended, while it
|
|
156
|
+
still held the lock; you can read it but not set it. A status stays readable for the server's
|
|
157
|
+
`state_ttl` (10 minutes by default; `set_status(..., ttl=...)` overrides it).
|
|
158
|
+
|
|
159
|
+
If the lease is lost while you hold the lock (the server restarted, a long network partition), `guard.lost`
|
|
160
|
+
turns true, and leaving the block raises `LockLost` (unless another exception is already propagating, which
|
|
161
|
+
is never masked). Call `guard.check()` before irreversible steps of a long job.
|
|
162
|
+
|
|
163
|
+
## Errors
|
|
164
|
+
|
|
165
|
+
Everything derives from `DistLockError`. Where a standard exception fits, it is also that:
|
|
166
|
+
`LockTimeout` is a `TimeoutError`, `ConnectionFailed` a `ConnectionError`, `InvalidArgument`/`ConfigError` a `ValueError`.
|
|
167
|
+
|
|
168
|
+
| exception | when |
|
|
169
|
+
|---|---|
|
|
170
|
+
| `ConfigError` | bad URL or settings |
|
|
171
|
+
| `AuthenticationError` | wrong client id / password |
|
|
172
|
+
| `ConnectionFailed` | server unreachable or not ready (the pool keeps retrying in the background) |
|
|
173
|
+
| `LockTimeout` / `LockBusy` | waited out (a lock not obtained, or an event not set, in time) / `wait=0` and it was taken |
|
|
174
|
+
| `LockLost` | the lease expired before release |
|
|
175
|
+
| `MaintenanceError` | a maintenance command could not be carried out; nothing changed |
|
|
176
|
+
| `SessionLost` | the server forgot the session; the client logs in again by itself, but old locks are gone |
|
|
177
|
+
| `ClientClosed` | the client was closed |
|
|
178
|
+
| `InvalidArgument` / `ServerError` | rejected argument / anything else the server reports |
|
|
179
|
+
|
|
180
|
+
## Staying alive
|
|
181
|
+
|
|
182
|
+
* **Leases renew themselves** for as long as a guard is held: every `ttl / 3` the Rust client sends a lease extension, on its
|
|
183
|
+
own threads. That is independent of Python, so a blocked event loop (`time.sleep` in async code), a CPU-bound loop holding the
|
|
184
|
+
GIL, or a client object that went out of scope cannot make a lease lapse. Each renewal attempt is bounded and retried on
|
|
185
|
+
another connection, so one hung connection cannot eat a lease either.
|
|
186
|
+
* **Heartbeats keep the pool's connections up.** Every connection pings the server at half the server's `ping_interval`
|
|
187
|
+
(default 10 s). A connection that hears nothing for a full interval is considered dead and replaced, and TCP keepalive
|
|
188
|
+
backs this up at the OS level.
|
|
189
|
+
* **The pool repairs itself.** Dropped connections are re-established with jittered backoff, rejoining the same session (your
|
|
190
|
+
locks are re-verified against the server's view); if the server forgot the session (a restart), the client logs in again and
|
|
191
|
+
any locks held through the old session report `lost`.
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
client.connections # pool connections up right now
|
|
195
|
+
client.reconnects # connections re-established since the start
|
|
196
|
+
await client.ping() # round-trip time to the server, in seconds (client.ping_sync() when blocking)
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
If every connection is down for more than ten seconds, calls raise `AuthenticationError` when the server refuses the credentials
|
|
200
|
+
on re-login (a rotated password), and `ConnectionFailed` (with the underlying reason) otherwise.
|
|
201
|
+
|
|
202
|
+
## Maintenance
|
|
203
|
+
|
|
204
|
+
```python
|
|
205
|
+
report = await client.maintenance.reset_users() # or client.maintenance.reset_users_sync()
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
Tells the server to re-read its users file (`DISTLOCK_USERS_FILE`) and swap it in. Logins are never refused or delayed while this
|
|
209
|
+
happens (the server swaps an immutable snapshot atomically). Users that are **gone from the file or now disabled are thrown
|
|
210
|
+
out**: their sessions end, their locks are released (the next holder sees `ABANDONED`, after the server's lock-delay) and the
|
|
211
|
+
server closes **every one of their TCP connections**, including yours if you removed yourself: you still get the report, with
|
|
212
|
+
`report.invoker_dropped` set, and after that your calls raise `AuthenticationError` until the user is added back, which this
|
|
213
|
+
client then notices by itself. Users added or re-enabled can log in; a changed password applies to new logins only.
|
|
214
|
+
|
|
215
|
+
| `ResetUsersReport` | |
|
|
216
|
+
|---|---|
|
|
217
|
+
| `added`, `removed`, `disabled`, `enabled`, `password_changed` | counts of users in each category (names are in the server log, not in the reply) |
|
|
218
|
+
| `sessions_closed`, `connections_closed` | what was thrown out |
|
|
219
|
+
| `invoker_dropped` | you were among them |
|
|
220
|
+
| `unchanged` | nothing at all changed |
|
|
221
|
+
|
|
222
|
+
If the file cannot be loaded you get `MaintenanceError`, nothing changes, and the old users stay in force. Calling it again is
|
|
223
|
+
always safe. There is no authorization beyond being logged in yet, so any client can send it; it can only make the server
|
|
224
|
+
re-read a file the administrator controls.
|
|
225
|
+
|
|
226
|
+
## Lifecycle
|
|
227
|
+
|
|
228
|
+
```python
|
|
229
|
+
async with DistLockClient.from_url(url) as client: # connects now; on exit ends the session
|
|
230
|
+
... # (the server releases every lock it still holds)
|
|
231
|
+
client.close_sync() # or: await client.close()
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Dropping the last reference to a guard releases its lock (without a status); a client that is simply
|
|
235
|
+
dropped stops its pool and leaves its session to expire on the server.
|
|
236
|
+
|
|
237
|
+
## Names on the wire
|
|
238
|
+
|
|
239
|
+
The server sees `namespace:family:name` with `family` one of `mutex`, `rw`, `sem`, or `event`. That is how a mutex
|
|
240
|
+
and a read/write lock with the same name stay separate, and how namespaces keep applications apart.
|
|
241
|
+
`:` is therefore not allowed in a namespace (it is fine inside a lock name).
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
[package]
|
|
2
|
+
name = "distlock-client"
|
|
3
|
+
description = "Async and blocking client for the distlock server"
|
|
4
|
+
readme = "README.md"
|
|
5
|
+
version.workspace = true
|
|
6
|
+
edition.workspace = true
|
|
7
|
+
license.workspace = true
|
|
8
|
+
repository.workspace = true
|
|
9
|
+
keywords.workspace = true
|
|
10
|
+
categories.workspace = true
|
|
11
|
+
|
|
12
|
+
[lints]
|
|
13
|
+
workspace = true
|
|
14
|
+
|
|
15
|
+
[dependencies]
|
|
16
|
+
bytes = "1.12.2"
|
|
17
|
+
distlock-proto = { version = "0.2.0", path = "../distlock-proto" }
|
|
18
|
+
futures-util = { version = "0.3.34", features = ["sink"] }
|
|
19
|
+
getrandom = "0.4.3"
|
|
20
|
+
prost = "0.14.6"
|
|
21
|
+
socket2 = { version = "0.6.5", features = ["all"] }
|
|
22
|
+
thiserror = "2.0.21"
|
|
23
|
+
tokio = { version = "1.54.1", features = ["rt-multi-thread", "macros", "net", "time", "sync"] }
|
|
24
|
+
tokio-util = { version = "0.7.20", features = ["codec"] }
|
|
25
|
+
tracing = "0.1.44"
|
|
26
|
+
|
|
27
|
+
[dev-dependencies]
|
|
28
|
+
bcrypt = "0.19.3"
|
|
29
|
+
distlock-server = { path = "../distlock-server" }
|
|
30
|
+
serde_json = "1.0.154"
|
|
31
|
+
tempfile = "3.27.0"
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# distlock-client
|
|
2
|
+
|
|
3
|
+
[](https://github.com/loggerheads-with-binary/distlock/actions/workflows/ci.yml)
|
|
4
|
+
[](https://github.com/loggerheads-with-binary/distlock/actions/workflows/release.yml)
|
|
5
|
+
[](https://codecov.io/gh/loggerheads-with-binary/distlock)
|
|
6
|
+
[](https://crates.io/crates/distlock-client)
|
|
7
|
+
[](https://docs.rs/distlock-client)
|
|
8
|
+
|
|
9
|
+
Async and blocking Rust client for the [distlock](https://github.com/loggerheads-with-binary/distlock)
|
|
10
|
+
lock server. It supports mutexes, read/write locks, semaphores and events.
|
|
11
|
+
|
|
12
|
+
```toml
|
|
13
|
+
[dependencies]
|
|
14
|
+
distlock-client = "0.2"
|
|
15
|
+
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
```rust
|
|
19
|
+
use distlock_client::{Acquire, DistLockClient, State};
|
|
20
|
+
|
|
21
|
+
#[tokio::main]
|
|
22
|
+
async fn main() -> distlock_client::Result<()> {
|
|
23
|
+
let client = DistLockClient {
|
|
24
|
+
client_id: "billing-service".into(),
|
|
25
|
+
password: "secret".into(),
|
|
26
|
+
..Default::default()
|
|
27
|
+
}
|
|
28
|
+
.connect()
|
|
29
|
+
.await?;
|
|
30
|
+
|
|
31
|
+
let lock = client.acquire(Acquire::mutex("nightly-report")).await?;
|
|
32
|
+
if lock.previous().map(|p| p.state) == Some(State::Succeeded) {
|
|
33
|
+
// somebody already did the work
|
|
34
|
+
}
|
|
35
|
+
// ... work; the lease is renewed for you, and `lock.is_lost()` tells you if it was lost ...
|
|
36
|
+
lock.release_with(Some(State::Succeeded), None).await?;
|
|
37
|
+
Ok(())
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
* **Async and blocking.** `DistLockClient::connect` gives the async `Client`. `connect_blocking` gives
|
|
42
|
+
`blocking::Client`, with the same operations.
|
|
43
|
+
* **One session, a pool of connections.** Dropped connections are re-established and the session is
|
|
44
|
+
re-joined. The locks you hold are re-verified against the server.
|
|
45
|
+
* **Leases renew themselves** while you hold the lock.
|
|
46
|
+
* **Lock names** are sent as `namespace:family:name` (family `mutex`, `rw` or `sem`), so a mutex and a
|
|
47
|
+
read/write lock with the same name never conflict.
|
|
48
|
+
|
|
49
|
+
The server is [`distlock-server`](https://crates.io/crates/distlock-server). Python users want
|
|
50
|
+
[`pydistlock`](https://pypi.org/project/pydistlock/), which wraps this crate.
|
|
51
|
+
|
|
52
|
+
Licensed under the [MIT license](https://github.com/loggerheads-with-binary/distlock/blob/main/LICENSE).
|