cli-watch-kit 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,324 @@
1
+ """The daemon transport: NDJSON, one request and one response per connection.
2
+
3
+ POSIX uses a Unix socket (`0600`) in the private state dir (`0700`), so requests may carry secrets such as an API
4
+ key. Windows uses loopback TCP on a random port; the port and a random token are in a file only the user can read,
5
+ and every request must carry the token, because any local user can connect to a loopback port. Setting
6
+ `<PREFIX>TRANSPORT=tcp` selects TCP on POSIX too, which is how the Windows path is tested on Linux.
7
+
8
+ The file names carry the library's and the app's protocol versions, so daemons of different protocols never meet.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import asyncio
14
+ import contextlib
15
+ import hmac
16
+ import json
17
+ import logging
18
+ import os
19
+ import secrets
20
+ import socket
21
+ import sys
22
+ from collections.abc import Awaitable, Callable
23
+ from dataclasses import dataclass
24
+ from pathlib import Path
25
+ from typing import TYPE_CHECKING, Any
26
+
27
+ from cli_watch_kit.locks import FileLock
28
+ from cli_watch_kit.paths import check_owned, ensure_private_dir
29
+
30
+ if TYPE_CHECKING:
31
+ from cli_watch_kit.app import WatchApp
32
+
33
+ log = logging.getLogger(__name__)
34
+
35
+ SHUTDOWN_GRACE = 1.0
36
+ """Seconds a stopping daemon gives the requests in flight before it cuts their connections."""
37
+ MAX_LINE = 64 * 1024 * 1024
38
+ """Enough for a large artifact, base64-encoded, in one response line."""
39
+
40
+ Handler = Callable[[dict[str, Any]], Awaitable[dict[str, Any]]]
41
+
42
+
43
+ class DaemonUnavailable(ConnectionError):
44
+ """No daemon answers on the endpoint."""
45
+
46
+
47
+ class DaemonTimeout(TimeoutError):
48
+ """The daemon took the request but did not answer in time. Unlike a gone daemon, it may still carry it out."""
49
+
50
+
51
+ class DaemonStartFailed(DaemonUnavailable):
52
+ """A daemon was started but failed before it listened; trying again would fail the same way."""
53
+
54
+
55
+ class DaemonHung(DaemonUnavailable):
56
+ """The daemon holds its lock but answers nothing, and could not be verified and killed."""
57
+
58
+
59
+ class DaemonNotTrusted(DaemonUnavailable):
60
+ """The daemon's files do not belong to this user alone, so secrets must not be sent to whatever listens there."""
61
+
62
+
63
+ class DaemonMismatch(RuntimeError):
64
+ """The daemon does not know a request: it runs other code than the watcher under the same protocol versions."""
65
+
66
+
67
+ MAX_SOCKET_PATH_BYTES = 103 if sys.platform == "darwin" else 107
68
+ """The longest Unix socket path the OS takes: `sun_path` holds 104 bytes on macOS and 108 on Linux, with a NUL."""
69
+
70
+
71
+ @dataclass(frozen=True)
72
+ class DaemonFiles:
73
+ """The daemon's files in its state dir. `transport_env` names the variable that selects TCP on POSIX."""
74
+
75
+ state_dir: Path
76
+ stem: str = "daemon"
77
+ transport_env: str = ""
78
+ state_dir_env: str = ""
79
+
80
+ @classmethod
81
+ def for_app(cls, app: WatchApp, state_dir: Path | None = None) -> DaemonFiles:
82
+ from cli_watch_kit.app import LIB_PROTOCOL
83
+
84
+ return cls(
85
+ state_dir or app.paths.state_dir(),
86
+ f"daemon-l{LIB_PROTOCOL}-a{app.app_protocol}",
87
+ app.env("TRANSPORT"),
88
+ app.paths.state_dir_env,
89
+ )
90
+
91
+ @property
92
+ def use_tcp(self) -> bool:
93
+ return (
94
+ os.name == "nt"
95
+ or (bool(self.transport_env) and os.environ.get(self.transport_env) == "tcp")
96
+ or not hasattr(socket, "AF_UNIX")
97
+ )
98
+
99
+ def _name(self, suffix: str) -> Path:
100
+ return self.state_dir / f"{self.stem}.{suffix}"
101
+
102
+ @property
103
+ def lock(self) -> Path:
104
+ return self._name("lock")
105
+
106
+ @property
107
+ def spawn_lock(self) -> Path:
108
+ return self.state_dir / f"spawn-{self.stem}.lock"
109
+
110
+ @property
111
+ def socket(self) -> Path:
112
+ return self._name("sock")
113
+
114
+ @property
115
+ def endpoint(self) -> Path:
116
+ return self._name("json")
117
+
118
+ @property
119
+ def log(self) -> Path:
120
+ return self._name("log")
121
+
122
+ @property
123
+ def transport_name(self) -> str:
124
+ return "tcp" if self.use_tcp else "unix"
125
+
126
+ def describe_endpoint(self) -> str:
127
+ return str(self.endpoint if self.use_tcp else self.socket)
128
+
129
+ def check_trusted(self) -> None:
130
+ """Raise :class:`DaemonNotTrusted` unless the state dir and the endpoint belong to this user and nobody else
131
+ can write them. Checked before a request that carries params."""
132
+ try:
133
+ check_owned(self.state_dir, directory=True, private=True)
134
+ if self.use_tcp:
135
+ check_owned(self.endpoint, private=True)
136
+ elif os.name != "nt":
137
+ info = os.lstat(self.socket)
138
+ if info.st_uid != os.getuid():
139
+ raise PermissionError(f"{self.socket} belongs to another user")
140
+ except FileNotFoundError as exc:
141
+ raise DaemonUnavailable(str(exc)) from exc
142
+ except PermissionError as exc:
143
+ raise DaemonNotTrusted(f"not sending secrets to the daemon: {exc}") from exc
144
+
145
+ def owner_pid(self) -> int | None:
146
+ """The pid the daemon wrote into its lock file, if any."""
147
+ try:
148
+ return int(self.lock.read_text(encoding="ascii").strip() or "x")
149
+ except (OSError, ValueError):
150
+ return None
151
+
152
+ def lock_held(self) -> bool:
153
+ """Whether a daemon process holds the lock, answering or not."""
154
+ probe = FileLock(self.lock)
155
+ if probe.try_acquire():
156
+ probe.release()
157
+ return False
158
+ return True
159
+
160
+ def check_socket_path(self) -> None:
161
+ """Fail with a clear message when the socket path is too long for a Unix socket. Without this, the daemon
162
+ dies at bind with only an empty log, and the watcher waits out its start timeout."""
163
+ if self.use_tcp:
164
+ return
165
+ length = len(os.fsencode(self.socket))
166
+ if length > MAX_SOCKET_PATH_BYTES:
167
+ hint = f"; set {self.state_dir_env} to a shorter dir" if self.state_dir_env else ""
168
+ raise DaemonUnavailable(
169
+ f"the daemon socket path {self.socket} is {length} bytes, above the {MAX_SOCKET_PATH_BYTES}-byte limit"
170
+ f" of Unix sockets{hint}"
171
+ )
172
+
173
+
174
+ def _write_private(path: Path, content: str) -> None:
175
+ tmp = path.with_suffix(".tmp")
176
+ fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
177
+ with os.fdopen(fd, "w", encoding="utf-8") as fh:
178
+ fh.write(content)
179
+ os.replace(tmp, path)
180
+
181
+
182
+ @dataclass
183
+ class Listener:
184
+ """The listening daemon: `cleanup` removes the endpoint file, `close` ends the server and its connections."""
185
+
186
+ server: asyncio.AbstractServer
187
+ cleanup: Callable[[], None]
188
+ connections: set[asyncio.Task[Any]]
189
+
190
+ async def close(self, grace: float = SHUTDOWN_GRACE) -> None:
191
+ """Stop accepting, give the requests in flight `grace` seconds to finish, then cut the rest.
192
+
193
+ `Server.wait_closed()` waits for every open connection since Python 3.12, so a silent or slow client would
194
+ otherwise keep the daemon, and its lock, alive until the connection's read timeout.
195
+ """
196
+ self.server.close()
197
+ pending = {t for t in self.connections if not t.done()}
198
+ if pending:
199
+ _, pending = await asyncio.wait(pending, timeout=grace)
200
+ for task in pending:
201
+ task.cancel()
202
+ if pending:
203
+ await asyncio.wait(pending, timeout=grace)
204
+ with contextlib.suppress(TimeoutError):
205
+ await asyncio.wait_for(self.server.wait_closed(), grace)
206
+
207
+
208
+ async def start_server(files: DaemonFiles, handler: Handler) -> Listener:
209
+ """Start listening on the daemon's endpoint."""
210
+ ensure_private_dir(files.state_dir)
211
+ token = secrets.token_hex(16) if files.use_tcp else None
212
+ connections: set[asyncio.Task[Any]] = set()
213
+
214
+ async def on_connection(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
215
+ task = asyncio.current_task()
216
+ if task is not None:
217
+ connections.add(task)
218
+ task.add_done_callback(connections.discard)
219
+ try:
220
+ line = await asyncio.wait_for(reader.readuntil(b"\n"), 10)
221
+ request = json.loads(line)
222
+ if not isinstance(request, dict):
223
+ response: dict[str, Any] = {"ok": False, "error": "request must be a JSON object"}
224
+ elif token is not None and not hmac.compare_digest(str(request.get("token", "")), token):
225
+ response = {"ok": False, "error": "bad token"}
226
+ else:
227
+ request.pop("token", None)
228
+ response = await handler(request)
229
+ writer.write(json.dumps(response, separators=(",", ":")).encode() + b"\n")
230
+ await writer.drain()
231
+ except (TimeoutError, asyncio.IncompleteReadError, asyncio.LimitOverrunError, ValueError, OSError):
232
+ pass
233
+ except Exception:
234
+ log.exception("a daemon connection failed")
235
+ finally:
236
+ writer.close()
237
+ with contextlib.suppress(OSError, ConnectionError):
238
+ await writer.wait_closed()
239
+
240
+ if token is None:
241
+ with contextlib.suppress(FileNotFoundError):
242
+ files.socket.unlink()
243
+ server = await asyncio.start_unix_server(on_connection, path=str(files.socket), limit=MAX_LINE)
244
+ os.chmod(files.socket, 0o600)
245
+
246
+ def cleanup() -> None:
247
+ with contextlib.suppress(OSError):
248
+ files.socket.unlink()
249
+
250
+ return Listener(server, cleanup, connections)
251
+
252
+ server = await asyncio.start_server(on_connection, host="127.0.0.1", port=0, limit=MAX_LINE)
253
+ port = server.sockets[0].getsockname()[1]
254
+ _write_private(files.endpoint, json.dumps({"port": port, "token": token, "pid": os.getpid()}))
255
+
256
+ def cleanup_tcp() -> None:
257
+ with contextlib.suppress(OSError):
258
+ files.endpoint.unlink()
259
+
260
+ return Listener(server, cleanup_tcp, connections)
261
+
262
+
263
+ def _connect(files: DaemonFiles, timeout: float) -> tuple[socket.socket, str | None]:
264
+ if files.use_tcp:
265
+ try:
266
+ endpoint = json.loads(files.endpoint.read_text(encoding="utf-8"))
267
+ port, token = int(endpoint["port"]), str(endpoint["token"])
268
+ except (OSError, ValueError, KeyError, TypeError) as exc:
269
+ raise DaemonUnavailable(f"no daemon endpoint in {files.endpoint}") from exc
270
+ if not files.lock_held():
271
+ # The port of a daemon that is gone may belong to anyone now; never send them the token.
272
+ raise DaemonUnavailable(f"the endpoint in {files.endpoint} is stale: no daemon holds {files.lock}")
273
+ try:
274
+ return socket.create_connection(("127.0.0.1", port), timeout=timeout), token
275
+ except OSError as exc:
276
+ raise DaemonUnavailable(str(exc)) from exc
277
+ sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
278
+ sock.settimeout(timeout)
279
+ try:
280
+ sock.connect(str(files.socket))
281
+ except OSError as exc:
282
+ sock.close()
283
+ raise DaemonUnavailable(str(exc)) from exc
284
+ return sock, None
285
+
286
+
287
+ def request(files: DaemonFiles, payload: dict[str, Any], timeout: float = 10.0) -> dict[str, Any]:
288
+ """Send one request and return the response.
289
+
290
+ Raises :class:`DaemonUnavailable` when no daemon listens, or it closed the connection or cut its answer short (a
291
+ request to a daemon that died is safe to send again), and :class:`DaemonTimeout` when it did not answer within
292
+ `timeout` seconds (it may still be working on it)."""
293
+ sock, token = _connect(files, timeout)
294
+ with sock:
295
+ body = dict(payload)
296
+ if token is not None:
297
+ body["token"] = token
298
+ chunks = []
299
+ try:
300
+ sock.sendall(json.dumps(body, separators=(",", ":")).encode() + b"\n")
301
+ total = 0
302
+ while True:
303
+ chunk = sock.recv(65536)
304
+ if not chunk:
305
+ break
306
+ chunks.append(chunk)
307
+ total += len(chunk)
308
+ if chunk.endswith(b"\n") or total > MAX_LINE:
309
+ break
310
+ except TimeoutError as exc:
311
+ # The daemon is there but slow; it may still carry out the request, so this is no reason to retry it.
312
+ raise DaemonTimeout(f"the daemon did not answer within {timeout:.0f} s") from exc
313
+ except OSError as exc:
314
+ raise DaemonUnavailable(str(exc)) from exc
315
+ raw = b"".join(chunks)
316
+ if not raw.strip():
317
+ raise DaemonUnavailable("the daemon closed the connection without answering")
318
+ try:
319
+ response = json.loads(raw)
320
+ except ValueError as exc:
321
+ raise DaemonUnavailable("the daemon's answer was cut off") from exc
322
+ if not isinstance(response, dict):
323
+ raise DaemonUnavailable("the daemon sent an unexpected response")
324
+ return response
@@ -0,0 +1,28 @@
1
+ """Durations as the options spell them: `90`, `90s`, `30m`, `2h`, `1h30m`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+
7
+ _DURATION_RE = re.compile(r"^(?:(?P<h>\d+)h)?(?:(?P<m>\d+)m)?(?:(?P<s>\d+)s)?$")
8
+
9
+
10
+ def parse_duration(value: str) -> float:
11
+ """Seconds in `value`. A bare number is seconds and may have a fraction."""
12
+ text = value.strip().lower()
13
+ if text.replace(".", "", 1).isdigit():
14
+ return float(text)
15
+ match = _DURATION_RE.match(text)
16
+ if not text or not match or not any(match.groupdict().values()):
17
+ raise ValueError(f"cannot read the duration {value!r}; use for example 90s, 30m, 2h or 1h30m")
18
+ parts = {k: int(v) if v else 0 for k, v in match.groupdict().items()}
19
+ return float(parts["h"] * 3600 + parts["m"] * 60 + parts["s"])
20
+
21
+
22
+ def format_duration(seconds: float) -> str:
23
+ """`90` -> `1m30s`, `7200` -> `2h`: the spelling :func:`parse_duration` reads back."""
24
+ total = int(round(seconds))
25
+ hours, rest = divmod(total, 3600)
26
+ minutes, secs = divmod(rest, 60)
27
+ text = (f"{hours}h" if hours else "") + (f"{minutes}m" if minutes else "") + (f"{secs}s" if secs else "")
28
+ return text or "0s"
@@ -0,0 +1,182 @@
1
+ """The event model, the catalog of event kinds a CLI reports, and the `--events`/`--exclude-events` filter.
2
+
3
+ Every watch reports the three lifecycle kinds, whatever the filter says: `watch_started` once the first snapshot is
4
+ known, `watch_degraded` once per kind of trouble, and `watch_ended` as the last event. The CLI names everything else
5
+ in a :class:`KindCatalog`: which kinds each resource kind produces, the groups the filter options accept, and the
6
+ threshold kinds that the watcher computes from time and that are reported only when their option is given.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from collections.abc import Iterable, Mapping
12
+ from dataclasses import dataclass, field
13
+ from datetime import UTC, datetime
14
+ from typing import Any
15
+
16
+ WATCH_STARTED = "watch_started"
17
+ WATCH_DEGRADED = "watch_degraded"
18
+ WATCH_ENDED = "watch_ended"
19
+ LIFECYCLE_KINDS: tuple[str, ...] = (WATCH_STARTED, WATCH_DEGRADED, WATCH_ENDED)
20
+ LIFECYCLE_GROUP = "lifecycle"
21
+
22
+
23
+ class FilterError(ValueError):
24
+ """An `--events`/`--exclude-events` value or a threshold option that cannot work; the message names the option."""
25
+
26
+
27
+ def split_values(values: Iterable[str] | None) -> list[str]:
28
+ """Flatten repeated and comma-separated option values."""
29
+ return [part.strip() for value in values or () for part in value.split(",") if part.strip()]
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class KindCatalog:
34
+ """The event kinds of one CLI.
35
+
36
+ - `kinds_by_resource`: for each resource kind (`issue`, `mr`, ...), the kinds a watch of it can report, threshold
37
+ kinds included. The lifecycle kinds are implied.
38
+ - `groups`: names that `--events`/`--exclude-events` expand to several kinds. A group may list kinds of several
39
+ resource kinds; it expands to those the watched resource produces. `lifecycle` is added.
40
+ - `thresholds`: kinds the watcher derives from time (see :mod:`cli_watch_kit.timers`), each with the option that
41
+ switches it on, such as `{"quiet": "--quiet-after"}`. They are never sent to the daemon.
42
+ """
43
+
44
+ kinds_by_resource: Mapping[str, tuple[str, ...]]
45
+ groups: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
46
+ thresholds: Mapping[str, str] = field(default_factory=dict)
47
+
48
+ def __post_init__(self) -> None:
49
+ if LIFECYCLE_GROUP in self.groups:
50
+ raise ValueError(f"the group name {LIFECYCLE_GROUP!r} is reserved")
51
+ unknown = set(self.thresholds) - self.all_kinds
52
+ if unknown:
53
+ raise ValueError(f"threshold kinds that no resource produces: {', '.join(sorted(unknown))}")
54
+
55
+ @property
56
+ def all_groups(self) -> Mapping[str, tuple[str, ...]]:
57
+ return {**self.groups, LIFECYCLE_GROUP: LIFECYCLE_KINDS}
58
+
59
+ @property
60
+ def all_kinds(self) -> frozenset[str]:
61
+ return frozenset(k for kinds in self.kinds_by_resource.values() for k in kinds) | frozenset(LIFECYCLE_KINDS)
62
+
63
+ def produced(self, resource_kind: str) -> tuple[str, ...]:
64
+ """The kinds a watch of `resource_kind` can report, without the lifecycle kinds."""
65
+ try:
66
+ return self.kinds_by_resource[resource_kind]
67
+ except KeyError:
68
+ raise FilterError(f"unknown resource kind {resource_kind!r}") from None
69
+
70
+ def daemon_kinds(self, kinds: Iterable[str]) -> frozenset[str]:
71
+ """`kinds` without the threshold kinds, which only the watcher computes."""
72
+ return frozenset(kinds) - frozenset(self.thresholds)
73
+
74
+ def groups_for(self, resource_kind: str) -> list[str]:
75
+ """The groups that mean something for a watch of `resource_kind`, lifecycle left out."""
76
+ produced = set(self.produced(resource_kind))
77
+ return [name for name, kinds in self.groups.items() if set(kinds) & produced]
78
+
79
+ def _expand(self, resource_kind: str, values: Iterable[str], option: str, enabled: frozenset[str]) -> set[str]:
80
+ produced = set(self.produced(resource_kind)) | set(LIFECYCLE_KINDS)
81
+ switched_off = set(self.thresholds) - enabled
82
+ groups = self.all_groups
83
+ expanded: set[str] = set()
84
+ for name in values:
85
+ if name in groups:
86
+ # A group brings a threshold kind only when its option is given: `--events=status` stays usable
87
+ # without the threshold option.
88
+ members = set(groups[name]) & produced - switched_off
89
+ if not members:
90
+ raise FilterError(f"{option}: the group {name!r} has no events for a {resource_kind} watch")
91
+ expanded |= members
92
+ elif name in self.all_kinds:
93
+ if name not in produced:
94
+ raise FilterError(f"{option}: a {resource_kind} watch never produces {name!r}")
95
+ if name in switched_off and option == "--events":
96
+ raise FilterError(f"{option}: {name!r} is reported only with {self.thresholds[name]}")
97
+ expanded.add(name)
98
+ else:
99
+ known = ", ".join(sorted(groups))
100
+ raise FilterError(f"{option}: unknown event kind or group {name!r} (groups: {known})")
101
+ return expanded
102
+
103
+ def resolve(
104
+ self,
105
+ resource_kind: str,
106
+ include: Iterable[str] | None,
107
+ exclude: Iterable[str] | None,
108
+ enabled: Iterable[str] = (),
109
+ ) -> frozenset[str]:
110
+ """The event kinds a watch reports. Lifecycle events are always in, and cannot be excluded.
111
+
112
+ `enabled` names the threshold kinds whose option was given. Without its option a threshold kind is never
113
+ reported, and with it the kind must survive the filter, so an option never silently does nothing.
114
+ """
115
+ enabled_set = frozenset(enabled)
116
+ produced = self.produced(resource_kind)
117
+ include_list = split_values(include)
118
+ exclude_list = split_values(exclude)
119
+ if include_list:
120
+ selected = self._expand(resource_kind, include_list, "--events", enabled_set)
121
+ else:
122
+ selected = set(produced) - (set(self.thresholds) - enabled_set)
123
+ if exclude_list:
124
+ excluded = self._expand(resource_kind, exclude_list, "--exclude-events", enabled_set)
125
+ if excluded & set(LIFECYCLE_KINDS):
126
+ raise FilterError("--exclude-events: lifecycle events are always reported and cannot be excluded")
127
+ selected -= excluded
128
+ for kind in sorted(enabled_set):
129
+ option = self.thresholds.get(kind, kind)
130
+ if kind not in produced:
131
+ raise FilterError(f"{option}: a {resource_kind} watch never produces {kind!r}")
132
+ if kind not in selected:
133
+ raise FilterError(f"{option}: {kind!r} is filtered out by --events/--exclude-events")
134
+ return frozenset(selected | set(LIFECYCLE_KINDS))
135
+
136
+
137
+ def utc_now_iso() -> str:
138
+ return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
139
+
140
+
141
+ @dataclass(frozen=True, slots=True)
142
+ class RawEvent:
143
+ """An event as a source produces it, before the engine assigns its sequence number."""
144
+
145
+ kind: str
146
+ data: dict[str, Any] = field(default_factory=dict)
147
+ artifacts: tuple[str, ...] = ()
148
+
149
+
150
+ @dataclass(frozen=True, slots=True)
151
+ class Event:
152
+ """One reported change. `resource` is the watched resource's key, `seq` its number in the stream."""
153
+
154
+ kind: str
155
+ resource: str
156
+ seq: int
157
+ observed_at: str
158
+ data: dict[str, Any]
159
+ artifacts: tuple[str, ...] = ()
160
+
161
+ def to_json(self) -> dict[str, Any]:
162
+ payload: dict[str, Any] = {
163
+ "kind": self.kind,
164
+ "resource": self.resource,
165
+ "seq": self.seq,
166
+ "observed_at": self.observed_at,
167
+ "data": self.data,
168
+ }
169
+ if self.artifacts:
170
+ payload["artifacts"] = list(self.artifacts)
171
+ return payload
172
+
173
+ @classmethod
174
+ def from_json(cls, data: Mapping[str, Any]) -> Event:
175
+ return cls(
176
+ kind=str(data["kind"]),
177
+ resource=str(data["resource"]),
178
+ seq=int(data["seq"]),
179
+ observed_at=str(data["observed_at"]),
180
+ data=dict(data.get("data") or {}),
181
+ artifacts=tuple(str(a) for a in data.get("artifacts") or ()),
182
+ )
cli_watch_kit/locks.py ADDED
@@ -0,0 +1,93 @@
1
+ """Exclusive OS file locks: `fcntl.flock` on POSIX, `msvcrt.locking` on Windows.
2
+
3
+ The OS releases the lock when the holding process dies, so a lock file left on disk means nothing. Being able to take
4
+ the daemon lock proves that no daemon is running.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import os
10
+ import sys
11
+ import time
12
+ from pathlib import Path
13
+ from types import TracebackType
14
+
15
+
16
+ class LockTimeout(TimeoutError):
17
+ pass
18
+
19
+
20
+ class FileLock:
21
+ def __init__(self, path: Path) -> None:
22
+ self.path = path
23
+ self._fd: int | None = None
24
+
25
+ @property
26
+ def held(self) -> bool:
27
+ return self._fd is not None
28
+
29
+ def _try_lock(self, fd: int) -> bool:
30
+ if sys.platform == "win32":
31
+ import msvcrt
32
+
33
+ try:
34
+ os.lseek(fd, 0, os.SEEK_SET)
35
+ msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
36
+ except OSError:
37
+ return False
38
+ return True
39
+ import fcntl
40
+
41
+ try:
42
+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
43
+ except OSError:
44
+ return False
45
+ return True
46
+
47
+ def try_acquire(self) -> bool:
48
+ if self._fd is not None:
49
+ return True
50
+ self.path.parent.mkdir(parents=True, exist_ok=True)
51
+ fd = os.open(self.path, os.O_RDWR | os.O_CREAT, 0o600)
52
+ if self._try_lock(fd):
53
+ self._fd = fd
54
+ return True
55
+ os.close(fd)
56
+ return False
57
+
58
+ def acquire(self, timeout: float) -> None:
59
+ deadline = time.monotonic() + timeout
60
+ while not self.try_acquire():
61
+ if time.monotonic() >= deadline:
62
+ raise LockTimeout(f"could not lock {self.path} within {timeout:.0f} s")
63
+ time.sleep(0.05)
64
+
65
+ def write_owner(self, text: str) -> None:
66
+ """Put `text` (the holder's pid) into the held lock file, for others to read; POSIX only, since Windows locks
67
+ the bytes against other readers."""
68
+ if self._fd is None or sys.platform == "win32":
69
+ return
70
+ os.ftruncate(self._fd, 0)
71
+ os.pwrite(self._fd, text.encode(), 0)
72
+
73
+ def release(self) -> None:
74
+ fd, self._fd = self._fd, None
75
+ if fd is None:
76
+ return
77
+ if sys.platform == "win32":
78
+ import msvcrt
79
+
80
+ try:
81
+ os.lseek(fd, 0, os.SEEK_SET)
82
+ msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
83
+ except OSError:
84
+ pass
85
+ os.close(fd)
86
+
87
+ def __enter__(self) -> FileLock:
88
+ return self
89
+
90
+ def __exit__(
91
+ self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
92
+ ) -> None:
93
+ self.release()