dflockd-client 1.0.0__tar.gz

dflockd_client-1.0.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: dflockd-client
+Version: 1.0.0
+Summary: dflockd python client
+Author: Matth Ingersoll
+Author-email: Matth Ingersoll <matth@mtingers.com>
+License-Expression: MIT
+Requires-Dist: pytest-asyncio>=1.3.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0 ; extra == 'dev'
+Requires-Dist: pyright>=1.1 ; extra == 'dev'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/mtingers/dflockd-client-py
+Project-URL: Repository, https://github.com/mtingers/dflockd-client-py
+Project-URL: Documentation, https://mtingers.github.io/dflockd-client-py/
+Project-URL: Bug Tracker, https://github.com/mtingers/dflockd-client-py/issues
+Project-URL: Changelog, https://github.com/mtingers/dflockd-client-py/blob/main/CHANGELOG.md
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# dflockd-client
+
+<!--toc:start-->
+- [dflockd-client](#dflockd-client)
+  - [Installation](#installation)
+  - [Quick start](#quick-start)
+    - [Async client](#async-client)
+    - [Sync client](#sync-client)
+    - [Manual acquire/release](#manual-acquirerelease)
+    - [Two-phase lock acquisition](#two-phase-lock-acquisition)
+    - [Parameters](#parameters)
+  - [Multi-server sharding](#multi-server-sharding)
+<!--toc:end-->
+
+A Python client library for [dflockd](https://github.com/mtingers/dflockd) — a lightweight distributed lock server with FIFO ordering, automatic lease expiry, and background renewal.
+
+## Installation
+
+```bash
+pip install dflockd-client
+```
+
+Or with uv:
+
+```bash
+uv add dflockd-client
+```
+
+## Quick start
+
+### Async client
+
+```python
+import asyncio
+from dflockd_client.client import DistributedLock
+
+async def main():
+    async with DistributedLock("my-key", acquire_timeout_s=10) as lock:
+        print(lock.token, lock.lease)
+        # critical section — lease auto-renews in background
+
+asyncio.run(main())
+```
+
+### Sync client
+
+```python
+from dflockd_client.sync_client import DistributedLock
+
+with DistributedLock("my-key", acquire_timeout_s=10) as lock:
+    print(lock.token, lock.lease)
+    # critical section — lease auto-renews in background thread
+```
+
+### Manual acquire/release
+
+Both clients support explicit `acquire()` / `release()` outside of a context manager:
+
+```python
+from dflockd_client.sync_client import DistributedLock
+
+lock = DistributedLock("my-key")
+if lock.acquire():
+    try:
+        pass  # critical section
+    finally:
+        lock.release()
+```
+
+### Two-phase lock acquisition
+
+The `enqueue()` / `wait()` methods split lock acquisition into two steps, allowing you to notify an external system after joining the queue but before blocking:
+
+```python
+from dflockd_client.sync_client import DistributedLock
+
+lock = DistributedLock("my-key")
+status = lock.enqueue()       # join queue, returns "acquired" or "queued"
+notify_external_system()      # your application logic here
+if lock.wait(timeout_s=10):   # block until granted (no-op if already acquired)
+    try:
+        pass  # critical section
+    finally:
+        lock.release()
+```
+
+Async equivalent:
+
+```python
+lock = DistributedLock("my-key")
+status = await lock.enqueue()
+await notify_external_system()
+if await lock.wait(timeout_s=10):
+    try:
+        pass  # critical section
+    finally:
+        await lock.release()
+```
+
+### Parameters
+
+| Parameter           | Default                 | Description                                                             |
+| ------------------- | ----------------------- | ----------------------------------------------------------------------- |
+| `key`               | _(required)_            | Lock name                                                               |
+| `acquire_timeout_s` | `10`                    | Seconds to wait for lock acquisition                                    |
+| `lease_ttl_s`       | `None` (server default) | Lease duration in seconds                                               |
+| `servers`           | `[("127.0.0.1", 6388)]` | List of `(host, port)` tuples                                           |
+| `sharding_strategy` | `stable_hash_shard`     | `Callable[[str, int], int]` — maps `(key, num_servers)` to server index |
+| `renew_ratio`       | `0.5`                   | Renew at `lease * ratio` seconds                                        |
+
+## Multi-server sharding
+
+When running multiple dflockd instances, the client can distribute keys across servers using consistent hashing. Each key always routes to the same server.
+
+```python
+from dflockd_client.sync_client import DistributedLock
+
+servers = [("server1", 6388), ("server2", 6388), ("server3", 6388)]
+
+with DistributedLock("my-key", servers=servers) as lock:
+    print(lock.token, lock.lease)
+```
+
+The default strategy uses `zlib.crc32` for stable, deterministic hashing. You can provide a custom strategy:
+
+```python
+from dflockd_client.sync_client import DistributedLock
+
+def my_strategy(key: str, num_servers: int) -> int:
+    """Route all keys to the first server."""
+    return 0
+
+with DistributedLock("my-key", servers=servers, sharding_strategy=my_strategy) as lock:
+    pass
+```

dflockd_client-1.0.0/README.md

@@ -0,0 +1,135 @@
+# dflockd-client
+
+<!--toc:start-->
+- [dflockd-client](#dflockd-client)
+  - [Installation](#installation)
+  - [Quick start](#quick-start)
+    - [Async client](#async-client)
+    - [Sync client](#sync-client)
+    - [Manual acquire/release](#manual-acquirerelease)
+    - [Two-phase lock acquisition](#two-phase-lock-acquisition)
+    - [Parameters](#parameters)
+  - [Multi-server sharding](#multi-server-sharding)
+<!--toc:end-->
+
+A Python client library for [dflockd](https://github.com/mtingers/dflockd) — a lightweight distributed lock server with FIFO ordering, automatic lease expiry, and background renewal.
+
+## Installation
+
+```bash
+pip install dflockd-client
+```
+
+Or with uv:
+
+```bash
+uv add dflockd-client
+```
+
+## Quick start
+
+### Async client
+
+```python
+import asyncio
+from dflockd_client.client import DistributedLock
+
+async def main():
+    async with DistributedLock("my-key", acquire_timeout_s=10) as lock:
+        print(lock.token, lock.lease)
+        # critical section — lease auto-renews in background
+
+asyncio.run(main())
+```
+
+### Sync client
+
+```python
+from dflockd_client.sync_client import DistributedLock
+
+with DistributedLock("my-key", acquire_timeout_s=10) as lock:
+    print(lock.token, lock.lease)
+    # critical section — lease auto-renews in background thread
+```
+
+### Manual acquire/release
+
+Both clients support explicit `acquire()` / `release()` outside of a context manager:
+
+```python
+from dflockd_client.sync_client import DistributedLock
+
+lock = DistributedLock("my-key")
+if lock.acquire():
+    try:
+        pass  # critical section
+    finally:
+        lock.release()
+```
+
+### Two-phase lock acquisition
+
+The `enqueue()` / `wait()` methods split lock acquisition into two steps, allowing you to notify an external system after joining the queue but before blocking:
+
+```python
+from dflockd_client.sync_client import DistributedLock
+
+lock = DistributedLock("my-key")
+status = lock.enqueue()       # join queue, returns "acquired" or "queued"
+notify_external_system()      # your application logic here
+if lock.wait(timeout_s=10):   # block until granted (no-op if already acquired)
+    try:
+        pass  # critical section
+    finally:
+        lock.release()
+```
+
+Async equivalent:
+
+```python
+lock = DistributedLock("my-key")
+status = await lock.enqueue()
+await notify_external_system()
+if await lock.wait(timeout_s=10):
+    try:
+        pass  # critical section
+    finally:
+        await lock.release()
+```
+
+### Parameters
+
+| Parameter           | Default                 | Description                                                             |
+| ------------------- | ----------------------- | ----------------------------------------------------------------------- |
+| `key`               | _(required)_            | Lock name                                                               |
+| `acquire_timeout_s` | `10`                    | Seconds to wait for lock acquisition                                    |
+| `lease_ttl_s`       | `None` (server default) | Lease duration in seconds                                               |
+| `servers`           | `[("127.0.0.1", 6388)]` | List of `(host, port)` tuples                                           |
+| `sharding_strategy` | `stable_hash_shard`     | `Callable[[str, int], int]` — maps `(key, num_servers)` to server index |
+| `renew_ratio`       | `0.5`                   | Renew at `lease * ratio` seconds                                        |
+
+## Multi-server sharding
+
+When running multiple dflockd instances, the client can distribute keys across servers using consistent hashing. Each key always routes to the same server.
+
+```python
+from dflockd_client.sync_client import DistributedLock
+
+servers = [("server1", 6388), ("server2", 6388), ("server3", 6388)]
+
+with DistributedLock("my-key", servers=servers) as lock:
+    print(lock.token, lock.lease)
+```
+
+The default strategy uses `zlib.crc32` for stable, deterministic hashing. You can provide a custom strategy:
+
+```python
+from dflockd_client.sync_client import DistributedLock
+
+def my_strategy(key: str, num_servers: int) -> int:
+    """Route all keys to the first server."""
+    return 0
+
+with DistributedLock("my-key", servers=servers, sharding_strategy=my_strategy) as lock:
+    pass
+```

dflockd_client-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "dflockd-client"
+version = "1.0.0"
+description = "dflockd python client"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Matth Ingersoll", email = "matth@mtingers.com" }]
+requires-python = ">=3.12"
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.9.28,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[project.optional-dependencies]
+dev = ["pytest-asyncio>=1.3.0", "pytest-cov>=7.0.0", "pyright>=1.1"]
+
+[dependency-groups]
+dev = [
+  "pytest-asyncio>=1.3.0",
+  "pytest-cov>=7.0.0",
+  "pyright>=1.1",
+  "ruff>=0.15.0",
+]
+docs = ["mkdocs>=1.6", "mkdocs-material>=9.5"]
+[project.urls]
+Homepage = "https://github.com/mtingers/dflockd-client-py"
+Repository = "https://github.com/mtingers/dflockd-client-py"
+Documentation = "https://mtingers.github.io/dflockd-client-py/"
+"Bug Tracker" = "https://github.com/mtingers/dflockd-client-py/issues"
+Changelog = "https://github.com/mtingers/dflockd-client-py/blob/main/CHANGELOG.md"

dflockd_client-1.0.0/src/dflockd_client/client.py

@@ -0,0 +1,312 @@
+import asyncio
+import contextlib
+import logging
+from dataclasses import dataclass, field
+
+from .sharding import DEFAULT_SERVERS, ShardingStrategy, stable_hash_shard
+
+log = logging.getLogger("dflockd-client")
+
+
+def _encode_lines(*lines: str) -> bytes:
+    return ("".join(f"{ln}\n" for ln in lines)).encode("utf-8")
+
+
+async def _readline(reader: asyncio.StreamReader) -> str:
+    raw = await reader.readline()
+    if raw == b"":
+        raise ConnectionError("server closed connection")
+    return raw.decode("utf-8").rstrip("\r\n")
+
+
+async def acquire(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    key: str,
+    acquire_timeout_s: int,
+    lease_ttl_s: int | None = None,
+) -> tuple[str, int]:
+    # l\nkey\n"<timeout> [<lease>]"\n
+    arg = (
+        str(acquire_timeout_s)
+        if lease_ttl_s is None
+        else f"{acquire_timeout_s} {lease_ttl_s}"
+    )
+
+    writer.write(_encode_lines("l", key, arg))
+    await writer.drain()
+
+    resp = await _readline(reader)
+    if resp == "timeout":
+        raise TimeoutError(f"timeout acquiring {key!r}")
+    if not resp.startswith("ok "):
+        raise RuntimeError(f"acquire failed: {resp!r}")
+
+    # ok <token> <lease>
+    parts = resp.split()
+    if len(parts) < 2:
+        raise RuntimeError(f"bad ok response: {resp!r}")
+    token = parts[1]
+    lease = int(parts[2]) if len(parts) >= 3 else 30
+    return token, lease
+
+
+async def renew(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    key: str,
+    token: str,
+    lease_ttl_s: int | None = None,
+) -> int:
+    # n\nkey\n"<token> [<lease>]"\n
+    arg = token if lease_ttl_s is None else f"{token} {lease_ttl_s}"
+    writer.write(_encode_lines("n", key, arg))
+    await writer.drain()
+
+    resp = await _readline(reader)
+    if not resp.startswith("ok"):
+        raise RuntimeError(f"renew failed: {resp!r}")
+
+    # ok <seconds_remaining> (optional)
+    parts = resp.split()
+    if len(parts) >= 2 and parts[1].isdigit():
+        return int(parts[1])
+    return -1
+
+
+async def enqueue(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    key: str,
+    lease_ttl_s: int | None = None,
+) -> tuple[str, str | None, int | None]:
+    """
+    Two-phase enqueue: join FIFO queue, return immediately.
+    Returns (status, token, lease) where status is "acquired" or "queued".
+    """
+    arg = "" if lease_ttl_s is None else str(lease_ttl_s)
+    writer.write(_encode_lines("e", key, arg))
+    await writer.drain()
+
+    resp = await _readline(reader)
+    if resp.startswith("acquired "):
+        parts = resp.split()
+        token = parts[1]
+        lease = int(parts[2]) if len(parts) >= 3 else 30
+        return ("acquired", token, lease)
+    if resp == "queued":
+        return ("queued", None, None)
+    raise RuntimeError(f"enqueue failed: {resp!r}")
+
+
+async def wait(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    key: str,
+    wait_timeout_s: int,
+) -> tuple[str, int]:
+    """
+    Two-phase wait: block until lock is granted.
+    Returns (token, lease). Raises TimeoutError on timeout.
+    """
+    writer.write(_encode_lines("w", key, str(wait_timeout_s)))
+    await writer.drain()
+
+    resp = await _readline(reader)
+    if resp == "timeout":
+        raise TimeoutError(f"timeout waiting for {key!r}")
+    if not resp.startswith("ok "):
+        raise RuntimeError(f"wait failed: {resp!r}")
+
+    parts = resp.split()
+    token = parts[1]
+    lease = int(parts[2]) if len(parts) >= 3 else 30
+    return token, lease
+
+
+async def release(
+    reader: asyncio.StreamReader, writer: asyncio.StreamWriter, key: str, token: str
+) -> None:
+    writer.write(_encode_lines("r", key, token))
+    await writer.drain()
+
+    resp = await _readline(reader)
+    if resp != "ok":
+        raise RuntimeError(f"release failed: {resp!r}")
+
+
+@dataclass
+class DistributedLock:
+    key: str
+    acquire_timeout_s: int = 10
+    lease_ttl_s: int | None = None  # if None, server default
+    servers: list[tuple[str, int]] = field(
+        default_factory=lambda: list(DEFAULT_SERVERS)
+    )
+    sharding_strategy: ShardingStrategy = stable_hash_shard
+    renew_ratio: float = 0.5  # renew at lease * ratio
+
+    _reader: asyncio.StreamReader | None = None
+    _writer: asyncio.StreamWriter | None = None
+    token: str | None = None
+    lease: int = 0
+    _renew_task: asyncio.Task | None = None
+    _closed: bool = False
+
+    def __post_init__(self):
+        if not self.servers:
+            raise ValueError("servers must be a non-empty list")
+
+    def _pick_server(self) -> tuple[str, int]:
+        idx = self.sharding_strategy(self.key, len(self.servers))
+        return self.servers[idx % len(self.servers)]
+
+    async def acquire(self) -> bool:
+        self._closed = False
+        host, port = self._pick_server()
+        self._reader, self._writer = await asyncio.open_connection(host, port)
+        try:
+            self.token, self.lease = await acquire(
+                self._reader,
+                self._writer,
+                self.key,
+                self.acquire_timeout_s,
+                self.lease_ttl_s,
+            )
+        except TimeoutError:
+            await self.aclose()
+            return False
+        except BaseException:
+            await self.aclose()
+            raise
+        # Start renew loop
+        self._renew_task = asyncio.create_task(self._renew_loop())
+        return True
+
+    async def enqueue(self) -> str:
+        """
+        Two-phase step 1: connect and enqueue. Returns "acquired" or "queued".
+        Starts renew loop on fast-path acquire.
+        """
+        self._closed = False
+        host, port = self._pick_server()
+        self._reader, self._writer = await asyncio.open_connection(host, port)
+        try:
+            status, tok, lease = await enqueue(
+                self._reader, self._writer, self.key, self.lease_ttl_s
+            )
+        except BaseException:
+            await self.aclose()
+            raise
+        if status == "acquired":
+            self.token = tok
+            self.lease = lease or 0
+            self._renew_task = asyncio.create_task(self._renew_loop())
+        return status
+
+    async def wait(self, timeout_s: int | None = None) -> bool:
+        """
+        Two-phase step 2: wait for lock grant. Returns True if granted, False on timeout.
+        If already acquired (fast path from enqueue), returns immediately.
+        """
+        if self.token is not None:
+            # Already acquired during enqueue
+            return True
+        if self._reader is None or self._writer is None:
+            raise RuntimeError("not connected; call enqueue() first")
+        timeout = timeout_s if timeout_s is not None else self.acquire_timeout_s
+        try:
+            self.token, self.lease = await wait(
+                self._reader, self._writer, self.key, timeout
+            )
+        except TimeoutError:
+            await self.aclose()
+            return False
+        except BaseException:
+            await self.aclose()
+            raise
+        self._renew_task = asyncio.create_task(self._renew_loop())
+        return True
+
+    async def release(self) -> bool:
+        try:
+            if self._renew_task:
+                self._renew_task.cancel()
+                with contextlib.suppress(BaseException):
+                    await self._renew_task
+
+            if self._reader and self._writer and self.token:
+                await release(self._reader, self._writer, self.key, self.token)
+        finally:
+            await self.aclose()
+        return True
+
+    async def __aenter__(self):
+        self._closed = False
+        host, port = self._pick_server()
+        self._reader, self._writer = await asyncio.open_connection(host, port)
+        try:
+            self.token, self.lease = await acquire(
+                self._reader,
+                self._writer,
+                self.key,
+                self.acquire_timeout_s,
+                self.lease_ttl_s,
+            )
+        except BaseException:
+            await self.aclose()
+            raise
+        # Start renew loop
+        self._renew_task = asyncio.create_task(self._renew_loop())
+        return self
+
+    async def _renew_loop(self):
+        assert self._reader and self._writer and self.token
+        interval = max(1.0, self.lease * self.renew_ratio)
+        try:
+            while True:
+                await asyncio.sleep(interval)
+                try:
+                    await renew(
+                        self._reader,
+                        self._writer,
+                        self.key,
+                        self.token,
+                        self.lease_ttl_s,
+                    )
+                except asyncio.CancelledError:
+                    raise
+                except Exception:
+                    log.error(
+                        "lock lost (renew failed): key=%s token=%s",
+                        self.key,
+                        self.token,
+                    )
+                    self.token = None
+                    return
+        except asyncio.CancelledError:
+            return
+
+    async def __aexit__(self, exc_type, exc, tb):
+        try:
+            if self._renew_task:
+                self._renew_task.cancel()
+                with contextlib.suppress(BaseException):
+                    await self._renew_task
+
+            if self._reader and self._writer and self.token:
+                await release(self._reader, self._writer, self.key, self.token)
+        finally:
+            await self.aclose()
+
+    async def aclose(self):
+        if self._closed:
+            return
+        self._closed = True
+        if self._writer:
+            self._writer.close()
+            with contextlib.suppress(Exception):
+                await self._writer.wait_closed()
+        self._reader = None
+        self._writer = None
+        self.token = None

dflockd_client-1.0.0/src/dflockd_client/sharding.py

@@ -0,0 +1,17 @@
+"""Sharding helpers for routing keys to servers."""
+
+import zlib
+from collections.abc import Callable
+
+ShardingStrategy = Callable[[str, int], int]
+
+DEFAULT_SERVERS: list[tuple[str, int]] = [("127.0.0.1", 6388)]
+
+
+def stable_hash_shard(key: str, num_servers: int) -> int:
+    """Return a server index for *key* using CRC-32.
+
+    Unlike the built-in ``hash()``, ``zlib.crc32`` is deterministic across
+    processes regardless of ``PYTHONHASHSEED``.
+    """
+    return zlib.crc32(key.encode("utf-8")) % num_servers

dflockd_client-1.0.0/src/dflockd_client/sync_client.py

@@ -0,0 +1,303 @@
+import io
+import logging
+import socket
+import threading
+from dataclasses import dataclass, field
+
+from .sharding import DEFAULT_SERVERS, ShardingStrategy, stable_hash_shard
+
+log = logging.getLogger("dflockd-client")
+
+
+def _encode_lines(*lines: str) -> bytes:
+    return ("".join(f"{ln}\n" for ln in lines)).encode("utf-8")
+
+
+def _readline(rfile: io.TextIOWrapper) -> str:
+    raw = rfile.readline()
+    if raw == "":
+        raise ConnectionError("server closed connection")
+    return raw.rstrip("\r\n")
+
+
+def acquire(
+    sock: socket.socket,
+    rfile: io.TextIOWrapper,
+    key: str,
+    acquire_timeout_s: int,
+    lease_ttl_s: int | None = None,
+) -> tuple[str, int]:
+    arg = (
+        str(acquire_timeout_s)
+        if lease_ttl_s is None
+        else f"{acquire_timeout_s} {lease_ttl_s}"
+    )
+
+    sock.sendall(_encode_lines("l", key, arg))
+
+    resp = _readline(rfile)
+    if resp == "timeout":
+        raise TimeoutError(f"timeout acquiring {key!r}")
+    if not resp.startswith("ok "):
+        raise RuntimeError(f"acquire failed: {resp!r}")
+
+    parts = resp.split()
+    if len(parts) < 2:
+        raise RuntimeError(f"bad ok response: {resp!r}")
+    token = parts[1]
+    lease = int(parts[2]) if len(parts) >= 3 else 30
+    return token, lease
+
+
+def renew(
+    sock: socket.socket,
+    rfile: io.TextIOWrapper,
+    key: str,
+    token: str,
+    lease_ttl_s: int | None = None,
+) -> int:
+    arg = token if lease_ttl_s is None else f"{token} {lease_ttl_s}"
+    sock.sendall(_encode_lines("n", key, arg))
+
+    resp = _readline(rfile)
+    if not resp.startswith("ok"):
+        raise RuntimeError(f"renew failed: {resp!r}")
+
+    parts = resp.split()
+    if len(parts) >= 2 and parts[1].isdigit():
+        return int(parts[1])
+    return -1
+
+
+def enqueue(
+    sock: socket.socket,
+    rfile: io.TextIOWrapper,
+    key: str,
+    lease_ttl_s: int | None = None,
+) -> tuple[str, str | None, int | None]:
+    """
+    Two-phase enqueue: join FIFO queue, return immediately.
+    Returns (status, token, lease) where status is "acquired" or "queued".
+    """
+    arg = "" if lease_ttl_s is None else str(lease_ttl_s)
+    sock.sendall(_encode_lines("e", key, arg))
+
+    resp = _readline(rfile)
+    if resp.startswith("acquired "):
+        parts = resp.split()
+        token = parts[1]
+        lease = int(parts[2]) if len(parts) >= 3 else 30
+        return ("acquired", token, lease)
+    if resp == "queued":
+        return ("queued", None, None)
+    raise RuntimeError(f"enqueue failed: {resp!r}")
+
+
+def wait(
+    sock: socket.socket,
+    rfile: io.TextIOWrapper,
+    key: str,
+    wait_timeout_s: int,
+) -> tuple[str, int]:
+    """
+    Two-phase wait: block until lock is granted.
+    Returns (token, lease). Raises TimeoutError on timeout.
+    """
+    sock.sendall(_encode_lines("w", key, str(wait_timeout_s)))
+
+    resp = _readline(rfile)
+    if resp == "timeout":
+        raise TimeoutError(f"timeout waiting for {key!r}")
+    if not resp.startswith("ok "):
+        raise RuntimeError(f"wait failed: {resp!r}")
+
+    parts = resp.split()
+    token = parts[1]
+    lease = int(parts[2]) if len(parts) >= 3 else 30
+    return token, lease
+
+
+def release(sock: socket.socket, rfile: io.TextIOWrapper, key: str, token: str) -> None:
+    sock.sendall(_encode_lines("r", key, token))
+
+    resp = _readline(rfile)
+    if resp != "ok":
+        raise RuntimeError(f"release failed: {resp!r}")
+
+
+@dataclass
+class DistributedLock:
+    key: str
+    acquire_timeout_s: int = 10
+    lease_ttl_s: int | None = None
+    servers: list[tuple[str, int]] = field(
+        default_factory=lambda: list(DEFAULT_SERVERS)
+    )
+    sharding_strategy: ShardingStrategy = stable_hash_shard
+    renew_ratio: float = 0.5
+
+    _sock: socket.socket | None = field(default=None, repr=False)
+    _rfile: io.TextIOWrapper | None = field(default=None, repr=False)
+    token: str | None = None
+    lease: int = 0
+    _renew_thread: threading.Thread | None = field(default=None, repr=False)
+    _stop_event: threading.Event = field(default_factory=threading.Event, repr=False)
+    _closed: bool = False
+
+    def __post_init__(self):
+        if not self.servers:
+            raise ValueError("servers must be a non-empty list")
+
+    def _pick_server(self) -> tuple[str, int]:
+        idx = self.sharding_strategy(self.key, len(self.servers))
+        return self.servers[idx % len(self.servers)]
+
+    def _connect(self):
+        self._closed = False
+        self._stop_event.clear()
+        host, port = self._pick_server()
+        self._sock = socket.create_connection((host, port))
+        self._rfile = self._sock.makefile("r", encoding="utf-8")
+
+    def _start_renew(self):
+        self._renew_thread = threading.Thread(target=self._renew_loop, daemon=True)
+        self._renew_thread.start()
+
+    def _stop_renew(self):
+        if self._renew_thread is not None:
+            self._stop_event.set()
+            self._renew_thread.join(timeout=5)
+            self._renew_thread = None
+
+    def acquire(self) -> bool:
+        self._connect()
+        sock, rfile = self._sock, self._rfile
+        assert sock is not None and rfile is not None
+        try:
+            self.token, self.lease = acquire(
+                sock,
+                rfile,
+                self.key,
+                self.acquire_timeout_s,
+                self.lease_ttl_s,
+            )
+        except TimeoutError:
+            self.close()
+            return False
+        except BaseException:
+            self.close()
+            raise
+        self._start_renew()
+        return True
+
+    def enqueue(self) -> str:
+        """
+        Two-phase step 1: connect and enqueue. Returns "acquired" or "queued".
+        Starts renew loop on fast-path acquire.
+        """
+        self._connect()
+        sock, rfile = self._sock, self._rfile
+        assert sock is not None and rfile is not None
+        try:
+            status, tok, lease = enqueue(sock, rfile, self.key, self.lease_ttl_s)
+        except BaseException:
+            self.close()
+            raise
+        if status == "acquired":
+            self.token = tok
+            self.lease = lease or 0
+            self._start_renew()
+        return status
+
+    def wait(self, timeout_s: int | None = None) -> bool:
+        """
+        Two-phase step 2: wait for lock grant. Returns True if granted, False on timeout.
+        If already acquired (fast path from enqueue), returns immediately.
+        """
+        if self.token is not None:
+            return True
+        sock, rfile = self._sock, self._rfile
+        if sock is None or rfile is None:
+            raise RuntimeError("not connected; call enqueue() first")
+        timeout = timeout_s if timeout_s is not None else self.acquire_timeout_s
+        try:
+            self.token, self.lease = wait(sock, rfile, self.key, timeout)
+        except TimeoutError:
+            self.close()
+            return False
+        except BaseException:
+            self.close()
+            raise
+        self._start_renew()
+        return True
+
+    def release(self) -> bool:
+        try:
+            self._stop_renew()
+            sock, rfile = self._sock, self._rfile
+            if sock is not None and rfile is not None and self.token:
+                release(sock, rfile, self.key, self.token)
+        finally:
+            self.close()
+        return True
+
+    def __enter__(self):
+        self._connect()
+        sock, rfile = self._sock, self._rfile
+        assert sock is not None and rfile is not None
+        try:
+            self.token, self.lease = acquire(
+                sock,
+                rfile,
+                self.key,
+                self.acquire_timeout_s,
+                self.lease_ttl_s,
+            )
+        except BaseException:
+            self.close()
+            raise
+        self._start_renew()
+        return self
+
+    def _renew_loop(self):
+        sock, rfile, token = self._sock, self._rfile, self.token
+        assert sock is not None and rfile is not None and token is not None
+        interval = max(1.0, self.lease * self.renew_ratio)
+        while not self._stop_event.wait(interval):
+            try:
+                renew(sock, rfile, self.key, token, self.lease_ttl_s)
+            except Exception:
+                log.error(
+                    "lock lost (renew failed): key=%s token=%s",
+                    self.key,
+                    self.token,
+                )
+                self.token = None
+                return
+
+    def __exit__(self, exc_type, exc, tb):
+        try:
+            self._stop_renew()
+            sock, rfile = self._sock, self._rfile
+            if sock is not None and rfile is not None and self.token:
+                release(sock, rfile, self.key, self.token)
+        finally:
+            self.close()
+
+    def close(self):
+        if self._closed:
+            return
+        self._closed = True
+        if self._rfile:
+            try:
+                self._rfile.close()
+            except Exception:
+                pass
+        if self._sock:
+            try:
+                self._sock.close()
+            except Exception:
+                pass
+        self._rfile = None
+        self._sock = None
+        self.token = None