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.
- cli_watch_kit/__init__.py +27 -0
- cli_watch_kit/app.py +175 -0
- cli_watch_kit/atomic.py +37 -0
- cli_watch_kit/budget.py +209 -0
- cli_watch_kit/changelog.py +87 -0
- cli_watch_kit/claude.py +195 -0
- cli_watch_kit/cli.py +410 -0
- cli_watch_kit/client.py +625 -0
- cli_watch_kit/daemon/__init__.py +25 -0
- cli_watch_kit/daemon/cache.py +48 -0
- cli_watch_kit/daemon/engine.py +874 -0
- cli_watch_kit/daemon/lifecycle.py +387 -0
- cli_watch_kit/daemon/scheduler.py +85 -0
- cli_watch_kit/daemon/server.py +116 -0
- cli_watch_kit/daemon/transport.py +324 -0
- cli_watch_kit/durations.py +28 -0
- cli_watch_kit/events.py +182 -0
- cli_watch_kit/locks.py +93 -0
- cli_watch_kit/paths.py +114 -0
- cli_watch_kit/py.typed +0 -0
- cli_watch_kit/sinks.py +106 -0
- cli_watch_kit/source.py +291 -0
- cli_watch_kit/timers.py +67 -0
- cli_watch_kit-0.1.0.dist-info/METADATA +207 -0
- cli_watch_kit-0.1.0.dist-info/RECORD +27 -0
- cli_watch_kit-0.1.0.dist-info/WHEEL +4 -0
- cli_watch_kit-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -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"
|
cli_watch_kit/events.py
ADDED
|
@@ -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()
|