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.
Files changed (45) hide show
  1. pydistlock-0.2.0/Cargo.toml +16 -0
  2. pydistlock-0.2.0/PKG-INFO +258 -0
  3. pydistlock-0.2.0/README.md +241 -0
  4. pydistlock-0.2.0/crates/distlock-client/Cargo.toml +31 -0
  5. pydistlock-0.2.0/crates/distlock-client/README.md +52 -0
  6. pydistlock-0.2.0/crates/distlock-client/src/blocking.rs +161 -0
  7. pydistlock-0.2.0/crates/distlock-client/src/client.rs +1507 -0
  8. pydistlock-0.2.0/crates/distlock-client/src/conn.rs +217 -0
  9. pydistlock-0.2.0/crates/distlock-client/src/error.rs +96 -0
  10. pydistlock-0.2.0/crates/distlock-client/src/event.rs +153 -0
  11. pydistlock-0.2.0/crates/distlock-client/src/lib.rs +46 -0
  12. pydistlock-0.2.0/crates/distlock-client/src/lock.rs +331 -0
  13. pydistlock-0.2.0/crates/distlock-client/src/maintenance.rs +85 -0
  14. pydistlock-0.2.0/crates/distlock-client/tests/blocking.rs +73 -0
  15. pydistlock-0.2.0/crates/distlock-client/tests/client.rs +637 -0
  16. pydistlock-0.2.0/crates/distlock-client/tests/common/mod.rs +328 -0
  17. pydistlock-0.2.0/crates/distlock-client/tests/events.rs +550 -0
  18. pydistlock-0.2.0/crates/distlock-client/tests/maintenance.rs +185 -0
  19. pydistlock-0.2.0/crates/distlock-client/tests/resilience.rs +231 -0
  20. pydistlock-0.2.0/crates/distlock-proto/Cargo.toml +20 -0
  21. pydistlock-0.2.0/crates/distlock-proto/README.md +23 -0
  22. pydistlock-0.2.0/crates/distlock-proto/build.rs +9 -0
  23. pydistlock-0.2.0/crates/distlock-proto/proto/distlock/v1/distlock.proto +357 -0
  24. pydistlock-0.2.0/crates/distlock-proto/src/lib.rs +107 -0
  25. pydistlock-0.2.0/distlock/__init__.py +61 -0
  26. pydistlock-0.2.0/distlock/_native.pyi +109 -0
  27. pydistlock-0.2.0/distlock/client.py +258 -0
  28. pydistlock-0.2.0/distlock/enums.py +45 -0
  29. pydistlock-0.2.0/distlock/errors.py +95 -0
  30. pydistlock-0.2.0/distlock/event.py +173 -0
  31. pydistlock-0.2.0/distlock/lock.py +353 -0
  32. pydistlock-0.2.0/distlock/maintenance.py +72 -0
  33. pydistlock-0.2.0/distlock/py.typed +0 -0
  34. pydistlock-0.2.0/distlock/settings.py +120 -0
  35. pydistlock-0.2.0/pyproject.toml +34 -0
  36. pydistlock-0.2.0/python/Cargo.lock +760 -0
  37. pydistlock-0.2.0/python/Cargo.toml +23 -0
  38. pydistlock-0.2.0/python/README.md +241 -0
  39. pydistlock-0.2.0/python/src/lib.rs +661 -0
  40. pydistlock-0.2.0/python/tests/conftest.py +185 -0
  41. pydistlock-0.2.0/python/tests/test_events.py +299 -0
  42. pydistlock-0.2.0/python/tests/test_locks.py +462 -0
  43. pydistlock-0.2.0/python/tests/test_maintenance.py +163 -0
  44. pydistlock-0.2.0/python/tests/test_resilience.py +199 -0
  45. 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
+ [![CI](https://github.com/loggerheads-with-binary/distlock/actions/workflows/ci.yml/badge.svg)](https://github.com/loggerheads-with-binary/distlock/actions/workflows/ci.yml)
20
+ [![Release](https://github.com/loggerheads-with-binary/distlock/actions/workflows/release.yml/badge.svg)](https://github.com/loggerheads-with-binary/distlock/actions/workflows/release.yml)
21
+ [![codecov](https://codecov.io/gh/loggerheads-with-binary/distlock/graph/badge.svg?component=pydistlock)](https://codecov.io/gh/loggerheads-with-binary/distlock)
22
+ [![PyPI](https://img.shields.io/pypi/v/pydistlock.svg)](https://pypi.org/project/pydistlock/)
23
+ [![Python](https://img.shields.io/pypi/pyversions/pydistlock.svg)](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
+ [![CI](https://github.com/loggerheads-with-binary/distlock/actions/workflows/ci.yml/badge.svg)](https://github.com/loggerheads-with-binary/distlock/actions/workflows/ci.yml)
4
+ [![Release](https://github.com/loggerheads-with-binary/distlock/actions/workflows/release.yml/badge.svg)](https://github.com/loggerheads-with-binary/distlock/actions/workflows/release.yml)
5
+ [![codecov](https://codecov.io/gh/loggerheads-with-binary/distlock/graph/badge.svg?component=pydistlock)](https://codecov.io/gh/loggerheads-with-binary/distlock)
6
+ [![PyPI](https://img.shields.io/pypi/v/pydistlock.svg)](https://pypi.org/project/pydistlock/)
7
+ [![Python](https://img.shields.io/pypi/pyversions/pydistlock.svg)](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
+ [![CI](https://github.com/loggerheads-with-binary/distlock/actions/workflows/ci.yml/badge.svg)](https://github.com/loggerheads-with-binary/distlock/actions/workflows/ci.yml)
4
+ [![Release](https://github.com/loggerheads-with-binary/distlock/actions/workflows/release.yml/badge.svg)](https://github.com/loggerheads-with-binary/distlock/actions/workflows/release.yml)
5
+ [![codecov](https://codecov.io/gh/loggerheads-with-binary/distlock/graph/badge.svg?component=distlock-client)](https://codecov.io/gh/loggerheads-with-binary/distlock)
6
+ [![crates.io](https://img.shields.io/crates/v/distlock-client.svg)](https://crates.io/crates/distlock-client)
7
+ [![docs.rs](https://docs.rs/distlock-client/badge.svg)](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).