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
cli_watch_kit/paths.py
ADDED
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
"""Filesystem locations of one app: the base dir its watchers write their files under, and the daemon state dir.
|
|
2
|
+
|
|
3
|
+
Each location can be overridden by an environment variable named after the app's prefix (`<PREFIX>BASE_DIR`,
|
|
4
|
+
`<PREFIX>STATE_DIR`), which also keeps tests inside temp dirs.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import os
|
|
10
|
+
import re
|
|
11
|
+
import stat
|
|
12
|
+
import sys
|
|
13
|
+
import tempfile
|
|
14
|
+
from dataclasses import dataclass
|
|
15
|
+
from pathlib import Path
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def sanitize_part(value: str) -> str:
|
|
19
|
+
"""Make one path component safe: no separators, no traversal, no characters Windows rejects."""
|
|
20
|
+
cleaned = re.sub(r"[^A-Za-z0-9._-]", "-", value).strip(".")
|
|
21
|
+
cleaned = cleaned.replace("..", "-")
|
|
22
|
+
return cleaned or "unknown"
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def ensure_private_dir(path: Path) -> Path:
|
|
26
|
+
"""Create `path` and make it readable by the user only.
|
|
27
|
+
|
|
28
|
+
A dir in a shared place such as `/tmp` may have been created by someone else first, or be a symlink to their dir;
|
|
29
|
+
such a dir is refused, because the daemon's socket and log, and the watchers' files, would then be theirs to read
|
|
30
|
+
or replace.
|
|
31
|
+
"""
|
|
32
|
+
path.mkdir(parents=True, exist_ok=True)
|
|
33
|
+
if os.name != "nt":
|
|
34
|
+
# Ours, then made private: the mode a fresh dir gets from the umask is no reason to refuse it.
|
|
35
|
+
check_owned(path, directory=True, modes=False)
|
|
36
|
+
os.chmod(path, 0o700)
|
|
37
|
+
return path
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def check_owned(path: Path, *, directory: bool = False, private: bool = False, modes: bool = True) -> None:
|
|
41
|
+
"""Raise `PermissionError` unless `path` belongs to this user, is no symlink, and (with `modes`) nobody else may
|
|
42
|
+
write it, or with `private` read it either. Does nothing on Windows, where the profile dir protects the files."""
|
|
43
|
+
if os.name == "nt":
|
|
44
|
+
return
|
|
45
|
+
info = os.lstat(path)
|
|
46
|
+
if stat.S_ISLNK(info.st_mode) or (directory and not stat.S_ISDIR(info.st_mode)):
|
|
47
|
+
raise PermissionError(f"{path} is a symlink or not a {'dir' if directory else 'file'}; refusing to use it")
|
|
48
|
+
if info.st_uid != os.getuid():
|
|
49
|
+
raise PermissionError(f"{path} belongs to another user; refusing to use it")
|
|
50
|
+
if modes and info.st_mode & (0o077 if private else 0o022):
|
|
51
|
+
raise PermissionError(
|
|
52
|
+
f"{path} is open to other users (mode {stat.S_IMODE(info.st_mode):o}); refusing to use it"
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def uid_suffix() -> str:
|
|
57
|
+
getuid = getattr(os, "getuid", None)
|
|
58
|
+
return str(getuid()) if getuid is not None else (os.environ.get("USERNAME") or "user")
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
@dataclass(frozen=True)
|
|
62
|
+
class AppPaths:
|
|
63
|
+
"""Where an app named `name` keeps its files. `env_prefix` is the prefix of its override variables.
|
|
64
|
+
`files_dir_name` names the dir of the watchers' files (default: `name`); the daemon's state dir keeps `name`."""
|
|
65
|
+
|
|
66
|
+
name: str
|
|
67
|
+
env_prefix: str
|
|
68
|
+
files_dir_name: str = ""
|
|
69
|
+
|
|
70
|
+
@property
|
|
71
|
+
def files_name(self) -> str:
|
|
72
|
+
return self.files_dir_name or self.name
|
|
73
|
+
|
|
74
|
+
@property
|
|
75
|
+
def base_dir_env(self) -> str:
|
|
76
|
+
return f"{self.env_prefix}BASE_DIR"
|
|
77
|
+
|
|
78
|
+
@property
|
|
79
|
+
def state_dir_env(self) -> str:
|
|
80
|
+
return f"{self.env_prefix}STATE_DIR"
|
|
81
|
+
|
|
82
|
+
def base_dir(self, override: Path | None = None, scratchpad: Path | None = None) -> Path:
|
|
83
|
+
"""The dir the watchers write their resource dirs under.
|
|
84
|
+
|
|
85
|
+
`override` wins, then `<PREFIX>BASE_DIR`. Under a Claude Code session with a scratchpad it is
|
|
86
|
+
`<scratchpad>/<files_dir_name>`, which Claude Code removes after a while. Otherwise
|
|
87
|
+
`<temp dir>/<files_dir_name>-<uid>`, private to the user, which the OS cleans.
|
|
88
|
+
"""
|
|
89
|
+
if override is not None:
|
|
90
|
+
return override
|
|
91
|
+
env = os.environ.get(self.base_dir_env)
|
|
92
|
+
if env:
|
|
93
|
+
return Path(env)
|
|
94
|
+
if scratchpad is not None:
|
|
95
|
+
return scratchpad / self.files_name
|
|
96
|
+
return ensure_private_dir(Path(tempfile.gettempdir()) / f"{self.files_name}-{uid_suffix()}")
|
|
97
|
+
|
|
98
|
+
def state_dir(self) -> Path:
|
|
99
|
+
"""The per-user dir holding the daemon's lock, socket (or port file) and log."""
|
|
100
|
+
override = os.environ.get(self.state_dir_env)
|
|
101
|
+
if override:
|
|
102
|
+
return Path(override)
|
|
103
|
+
if sys.platform == "win32":
|
|
104
|
+
base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
|
|
105
|
+
return base / self.name / "run"
|
|
106
|
+
if sys.platform == "darwin":
|
|
107
|
+
tmpdir = os.environ.get("TMPDIR")
|
|
108
|
+
if tmpdir:
|
|
109
|
+
return Path(tmpdir) / self.name
|
|
110
|
+
else:
|
|
111
|
+
runtime = os.environ.get("XDG_RUNTIME_DIR")
|
|
112
|
+
if runtime and Path(runtime).is_dir():
|
|
113
|
+
return Path(runtime) / self.name
|
|
114
|
+
return Path(tempfile.gettempdir()) / f"{self.name}-{uid_suffix()}"
|
cli_watch_kit/py.typed
ADDED
|
File without changes
|
cli_watch_kit/sinks.py
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
"""Where a watcher delivers its events, and where its own status lines go.
|
|
2
|
+
|
|
3
|
+
Status lines (the startup header, the end line, errors) go to stderr, so stdout carries only events. Claude Code puts
|
|
4
|
+
a background Bash task's stderr into the task output next to its stdout, so an agent reads both. Status lines start
|
|
5
|
+
with the app's prefix and never with `{`, so a reader of the merged output can still tell them from events.
|
|
6
|
+
|
|
7
|
+
:class:`EventSink` has the shape of cc-blackbox's event sinks, so its `MessageEventSink` fits without an adapter;
|
|
8
|
+
see :mod:`cli_watch_kit.claude`.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import json
|
|
14
|
+
import sys
|
|
15
|
+
from collections.abc import Mapping, Sequence
|
|
16
|
+
from typing import Any, Protocol, TextIO, TypeVar
|
|
17
|
+
|
|
18
|
+
from cli_watch_kit.events import Event
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class StreamEvent(Protocol):
|
|
22
|
+
@property
|
|
23
|
+
def kind(self) -> str: ...
|
|
24
|
+
|
|
25
|
+
@property
|
|
26
|
+
def seq(self) -> int: ...
|
|
27
|
+
|
|
28
|
+
def to_json(self) -> Mapping[str, Any]: ...
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
E_contra = TypeVar("E_contra", bound=StreamEvent, contravariant=True)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class EventSink(Protocol[E_contra]):
|
|
35
|
+
"""Where a watcher delivers its events. The watcher calls :meth:`tick` when :meth:`seconds_until_flush` says so."""
|
|
36
|
+
|
|
37
|
+
name: str
|
|
38
|
+
|
|
39
|
+
def describe(self) -> str:
|
|
40
|
+
"""One line for the startup header: the stream mode and its target."""
|
|
41
|
+
...
|
|
42
|
+
|
|
43
|
+
def emit(self, events: Sequence[E_contra]) -> None: ...
|
|
44
|
+
|
|
45
|
+
def seconds_until_flush(self) -> float | None:
|
|
46
|
+
"""When a buffered batch is due, so the watcher wakes up for it; `None` when nothing is buffered."""
|
|
47
|
+
...
|
|
48
|
+
|
|
49
|
+
def tick(self) -> None:
|
|
50
|
+
"""Deliver a buffered batch whose time has come."""
|
|
51
|
+
...
|
|
52
|
+
|
|
53
|
+
def alive(self) -> bool:
|
|
54
|
+
"""`False` once the target is gone, which ends the watch."""
|
|
55
|
+
...
|
|
56
|
+
|
|
57
|
+
def close(self) -> None: ...
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
type Sink = EventSink[Event]
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
class StdoutSink:
|
|
64
|
+
"""One compact JSON object per line, flushed after every batch."""
|
|
65
|
+
|
|
66
|
+
name = "stdout"
|
|
67
|
+
|
|
68
|
+
def __init__(self, stream: TextIO | None = None) -> None:
|
|
69
|
+
self._stream = stream
|
|
70
|
+
|
|
71
|
+
def describe(self) -> str:
|
|
72
|
+
return "stdout (one JSON event per line)"
|
|
73
|
+
|
|
74
|
+
def emit(self, events: Sequence[StreamEvent]) -> None:
|
|
75
|
+
stream = self._stream or sys.stdout
|
|
76
|
+
for event in events:
|
|
77
|
+
stream.write(json.dumps(event.to_json(), ensure_ascii=False, separators=(",", ":")) + "\n")
|
|
78
|
+
stream.flush()
|
|
79
|
+
|
|
80
|
+
def seconds_until_flush(self) -> float | None:
|
|
81
|
+
return None
|
|
82
|
+
|
|
83
|
+
def tick(self) -> None:
|
|
84
|
+
pass
|
|
85
|
+
|
|
86
|
+
def alive(self) -> bool:
|
|
87
|
+
return True
|
|
88
|
+
|
|
89
|
+
def close(self) -> None:
|
|
90
|
+
pass
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
class StatusOutput:
|
|
94
|
+
"""Status lines with the app's prefix, on stderr unless a stream is given."""
|
|
95
|
+
|
|
96
|
+
def __init__(self, prefix: str, stream: TextIO | None = None) -> None:
|
|
97
|
+
self.prefix = prefix
|
|
98
|
+
self._stream = stream
|
|
99
|
+
|
|
100
|
+
@property
|
|
101
|
+
def stream(self) -> TextIO:
|
|
102
|
+
return self._stream if self._stream is not None else sys.stderr
|
|
103
|
+
|
|
104
|
+
def line(self, text: str) -> None:
|
|
105
|
+
self.stream.write(f"{self.prefix}{text}\n")
|
|
106
|
+
self.stream.flush()
|
cli_watch_kit/source.py
ADDED
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
"""What a CLI implements to be watched: a :class:`Source` that polls targets and diffs them into events.
|
|
2
|
+
|
|
3
|
+
The engine owns the scheduling, the rate budget, the sharing between watchers and the event log. The source owns the
|
|
4
|
+
API: it fetches the current state of a batch of targets, diffs each against the previous snapshot with a pure
|
|
5
|
+
function, and returns one :class:`PollOutcome` per target. It never sleeps and never retries; the engine does both.
|
|
6
|
+
|
|
7
|
+
- A **target** is what a watcher asks for (`issue ABC-123`). Its `key` names it in events and logs.
|
|
8
|
+
- An **account** is whose rate limit a poll spends. Targets of different accounts never share a poll or a budget,
|
|
9
|
+
so two watchers with different API keys of the same user share one budget, and two users never share one.
|
|
10
|
+
- Targets with the same **batch key** that are due at about the same time go into one :meth:`Source.poll` call, split
|
|
11
|
+
so that no call costs more than :attr:`Source.batch_cost_cap`.
|
|
12
|
+
- **Params** are what a watcher sends along with its subscription, such as an API key. They reach the daemon over its
|
|
13
|
+
private socket and are given to the source per account, never logged or shown in the status.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import time
|
|
19
|
+
from abc import ABC, abstractmethod
|
|
20
|
+
from collections.abc import Awaitable, Callable, Hashable, Mapping, Sequence
|
|
21
|
+
from contextvars import ContextVar
|
|
22
|
+
from dataclasses import dataclass, field
|
|
23
|
+
from typing import TYPE_CHECKING, Any
|
|
24
|
+
|
|
25
|
+
from cli_watch_kit.budget import DEFAULT_DIMENSIONS, REQUESTS, Budget, DimensionSpec
|
|
26
|
+
from cli_watch_kit.daemon.cache import ByteBoundedCache
|
|
27
|
+
from cli_watch_kit.events import KindCatalog, RawEvent
|
|
28
|
+
|
|
29
|
+
if TYPE_CHECKING:
|
|
30
|
+
from cli_watch_kit.daemon.engine import Engine
|
|
31
|
+
|
|
32
|
+
Params = Mapping[str, Any]
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class SourceError(Exception):
|
|
36
|
+
"""A poll of a target failed. Raise a subclass from :meth:`Source.poll` for the whole batch, or put one in a
|
|
37
|
+
:class:`PollOutcome` for one target. The engine reports each kind once as `watch_degraded` and backs off."""
|
|
38
|
+
|
|
39
|
+
reason = "error"
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class NotFound(SourceError):
|
|
43
|
+
"""The target does not exist (any more). Before the first successful poll this ends the watch."""
|
|
44
|
+
|
|
45
|
+
reason = "not_found"
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class Unauthorized(SourceError):
|
|
49
|
+
reason = "auth"
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class RateLimited(SourceError):
|
|
53
|
+
"""The API refused the request for its rate limit. Blocks the whole account for `retry_after` seconds or more."""
|
|
54
|
+
|
|
55
|
+
reason = "rate_limited"
|
|
56
|
+
|
|
57
|
+
def __init__(self, message: str, retry_after: float | None = None) -> None:
|
|
58
|
+
super().__init__(message)
|
|
59
|
+
self.retry_after = retry_after
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
class Transient(SourceError):
|
|
63
|
+
"""A network error, a 5xx, an unexpected response: worth trying again later."""
|
|
64
|
+
|
|
65
|
+
reason = "error"
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
@dataclass(frozen=True)
|
|
69
|
+
class Target:
|
|
70
|
+
"""A watched resource: its `kind` (a key of the catalog's `kinds_by_resource`), an `id` unique within the kind,
|
|
71
|
+
and whatever else the source needs to poll it, as JSON in `data`. Two targets are equal when their keys are."""
|
|
72
|
+
|
|
73
|
+
kind: str
|
|
74
|
+
id: str
|
|
75
|
+
data: Mapping[str, Any] = field(default_factory=dict, compare=False, hash=False)
|
|
76
|
+
|
|
77
|
+
@property
|
|
78
|
+
def key(self) -> str:
|
|
79
|
+
return f"{self.kind} {self.id}"
|
|
80
|
+
|
|
81
|
+
def to_wire(self) -> dict[str, Any]:
|
|
82
|
+
return {"kind": self.kind, "id": self.id, "data": dict(self.data)}
|
|
83
|
+
|
|
84
|
+
@classmethod
|
|
85
|
+
def from_wire(cls, value: Any) -> Target:
|
|
86
|
+
if not isinstance(value, Mapping):
|
|
87
|
+
raise ValueError("target must be an object")
|
|
88
|
+
kind, ident, data = value.get("kind"), value.get("id"), value.get("data") or {}
|
|
89
|
+
if not isinstance(kind, str) or not kind or not isinstance(ident, str) or not ident:
|
|
90
|
+
raise ValueError("target.kind and target.id must be non-empty strings")
|
|
91
|
+
if not isinstance(data, Mapping):
|
|
92
|
+
raise ValueError("target.data must be an object")
|
|
93
|
+
return cls(kind, ident, dict(data))
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
@dataclass(frozen=True)
|
|
97
|
+
class PollItem[S]:
|
|
98
|
+
"""One target in a poll: the snapshot to diff against (`None` on the first poll without a baseline) and the event
|
|
99
|
+
kinds any subscriber wants, which a source may use to skip work nobody needs.
|
|
100
|
+
|
|
101
|
+
`state` is the resource's private scratch space for what is not part of the snapshot (an ETag, work held back
|
|
102
|
+
for a later poll, a stateful poller object). It is the same dict on every poll of the resource, starts empty
|
|
103
|
+
(also after a daemon restart), and goes away with the resource.
|
|
104
|
+
"""
|
|
105
|
+
|
|
106
|
+
target: Target
|
|
107
|
+
snapshot: S | None
|
|
108
|
+
events: frozenset[str]
|
|
109
|
+
state: dict[str, Any] = field(default_factory=dict, compare=False)
|
|
110
|
+
options: tuple[Mapping[str, Any], ...] = ()
|
|
111
|
+
"""The source options of every subscriber and parent that sent any, each once, for the source to merge (glab's
|
|
112
|
+
`--logs` modes, for example). Empty when nobody sent options."""
|
|
113
|
+
|
|
114
|
+
@property
|
|
115
|
+
def key(self) -> str:
|
|
116
|
+
return self.target.key
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
@dataclass(frozen=True)
|
|
120
|
+
class Wants:
|
|
121
|
+
"""What a parent wants from a child target: event kinds, and source options like a subscriber's.
|
|
122
|
+
|
|
123
|
+
`baseline` is the child's snapshot as the parent's snapshot knows it, in the child's :meth:`Source.encode` form.
|
|
124
|
+
A new child starts from it, so after a daemon restart the child's first poll reports what changed in the gap
|
|
125
|
+
instead of being a silent baseline poll. It works only when the parent's snapshot embeds the child state that
|
|
126
|
+
the relayed events depend on; without it the changes of a child during a restart are not reported.
|
|
127
|
+
"""
|
|
128
|
+
|
|
129
|
+
events: frozenset[str]
|
|
130
|
+
options: Mapping[str, Any] = field(default_factory=dict)
|
|
131
|
+
baseline: Any = None
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
@dataclass(frozen=True)
|
|
135
|
+
class PollOutcome[S]:
|
|
136
|
+
"""What a poll found for one target.
|
|
137
|
+
|
|
138
|
+
- On success, `snapshot` is the new state and `events` what changed since the previous one. A poll without a
|
|
139
|
+
previous snapshot is the baseline and should report nothing.
|
|
140
|
+
- `ended` ends the watch with that reason (`completed`, `merged`, ...), `end_data` goes into `watch_ended`.
|
|
141
|
+
- `next_delay` overrides :meth:`Source.interval` for this target once.
|
|
142
|
+
- With `error`, the rest is ignored.
|
|
143
|
+
"""
|
|
144
|
+
|
|
145
|
+
snapshot: S | None = None
|
|
146
|
+
events: Sequence[RawEvent] = ()
|
|
147
|
+
ended: str | None = None
|
|
148
|
+
end_data: Mapping[str, Any] = field(default_factory=dict)
|
|
149
|
+
next_delay: float | None = None
|
|
150
|
+
error: SourceError | None = None
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
@dataclass
|
|
154
|
+
class PollContext:
|
|
155
|
+
"""What a poll gets from the engine besides its targets.
|
|
156
|
+
|
|
157
|
+
`budget` is the account's: call :meth:`Budget.observe` with the rate-limit readings of each response.
|
|
158
|
+
|
|
159
|
+
The engine charges the account :meth:`Source.cost` before the call. A source that knows what each response really
|
|
160
|
+
cost (an ETag 304 at a tenth of a request, a complexity header) calls :meth:`spend` with it, as often as it sends
|
|
161
|
+
requests; after the call the engine gives back the estimate of each dimension the source spent on, so the account
|
|
162
|
+
pays what was spent there and the estimate elsewhere. `cache` is
|
|
163
|
+
shared by the whole daemon; put the version of the value into its key, so a hit is never stale.
|
|
164
|
+
"""
|
|
165
|
+
|
|
166
|
+
account: str
|
|
167
|
+
params: Params
|
|
168
|
+
budget: Budget
|
|
169
|
+
cache: ByteBoundedCache[Any]
|
|
170
|
+
clock: Callable[[], float] = time.time
|
|
171
|
+
estimate: Mapping[str, float] = field(default_factory=dict)
|
|
172
|
+
"""What the engine charged before the call."""
|
|
173
|
+
spent: dict[str, float] = field(default_factory=dict)
|
|
174
|
+
"""What :meth:`spend` charged so far."""
|
|
175
|
+
|
|
176
|
+
def spend(self, cost: Mapping[str, float]) -> None:
|
|
177
|
+
"""Charge what a request really cost. The estimate of each dimension spent on is refunded after the poll."""
|
|
178
|
+
self.budget.charge(cost, self.clock())
|
|
179
|
+
for dim, amount in cost.items():
|
|
180
|
+
self.spent[dim] = self.spent.get(dim, 0.0) + amount
|
|
181
|
+
|
|
182
|
+
@staticmethod
|
|
183
|
+
def current() -> PollContext | None:
|
|
184
|
+
"""The context of the poll the calling task runs in, or `None` outside a poll (in an extra op, say).
|
|
185
|
+
|
|
186
|
+
For an API client the source shares between the polls of an account, which can then charge each request to
|
|
187
|
+
the poll that sent it without the context being passed down to it. Concurrent polls each see their own."""
|
|
188
|
+
return _CURRENT_POLL.get()
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
_CURRENT_POLL: ContextVar[PollContext | None] = ContextVar("cli_watch_kit_current_poll", default=None)
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
@dataclass
|
|
195
|
+
class OpContext:
|
|
196
|
+
"""What an extra op of the daemon gets: the engine and the params the request carried."""
|
|
197
|
+
|
|
198
|
+
engine: Engine
|
|
199
|
+
params: Params
|
|
200
|
+
|
|
201
|
+
async def account(self, target: Target) -> str:
|
|
202
|
+
return await self.engine.source.account(target, self.params)
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
OpHandler = Callable[[OpContext, dict[str, Any]], Awaitable[dict[str, Any]]]
|
|
206
|
+
"""An extra daemon op: gets the request (without `op` and `params`) and returns the fields of the `ok` response."""
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
class Source[S](ABC):
|
|
210
|
+
"""The base class of a CLI's source. `S` is the source's snapshot type, which never leaves the daemon as is:
|
|
211
|
+
:meth:`encode` turns it into JSON for the watchers and their baselines, :meth:`decode` reads it back."""
|
|
212
|
+
|
|
213
|
+
catalog: KindCatalog
|
|
214
|
+
dimensions: Mapping[str, DimensionSpec] = DEFAULT_DIMENSIONS
|
|
215
|
+
"""The budget dimensions, with their rates before the API reports any."""
|
|
216
|
+
batch_cost_cap: Mapping[str, float] | None = None
|
|
217
|
+
"""The most one poll call may cost per dimension. Batches above it are split; one target above it polls alone."""
|
|
218
|
+
coalesce_window: float = 5.0
|
|
219
|
+
"""A target due within this many seconds joins a batch that polls now, so close schedules merge."""
|
|
220
|
+
baseline_wait: float | None = None
|
|
221
|
+
"""How long the first poll of a new target with a batch key waits, so the targets that watchers subscribe to
|
|
222
|
+
within a few seconds of each other share one call. `None` waits the `coalesce_window`; 0 polls at once."""
|
|
223
|
+
max_inflight: int = 4
|
|
224
|
+
"""Concurrent poll calls per account."""
|
|
225
|
+
ops: Mapping[str, OpHandler] = {}
|
|
226
|
+
"""Extra daemon ops, by name. They must not shadow the built-in ones."""
|
|
227
|
+
|
|
228
|
+
async def account(self, target: Target, params: Params) -> str:
|
|
229
|
+
"""Whose budget polls of `target` spend. Called on subscribe; raise :class:`Unauthorized` for bad params.
|
|
230
|
+
|
|
231
|
+
The params of the latest subscription of an account replace those of the earlier ones for every poll of the
|
|
232
|
+
account, so check them here, for example by resolving the user an API key belongs to: a subscription with a
|
|
233
|
+
wrong key that got through would break the account's other watchers. The default is one account for
|
|
234
|
+
everything."""
|
|
235
|
+
return ""
|
|
236
|
+
|
|
237
|
+
def batch_key(self, target: Target) -> Hashable | None:
|
|
238
|
+
"""Targets with an equal key (within one account) may be polled in one call. `None` polls alone."""
|
|
239
|
+
return None
|
|
240
|
+
|
|
241
|
+
@abstractmethod
|
|
242
|
+
def interval(self, target: Target, snapshot: S | None) -> float:
|
|
243
|
+
"""Base seconds until the next poll, before the engine stretches it under budget pressure."""
|
|
244
|
+
|
|
245
|
+
def cost(self, batch: Sequence[PollItem[S]]) -> Mapping[str, float]:
|
|
246
|
+
"""The estimated cost of one poll call for `batch`, per dimension. Default: one request."""
|
|
247
|
+
return {REQUESTS: 1.0}
|
|
248
|
+
|
|
249
|
+
@abstractmethod
|
|
250
|
+
async def poll(self, batch: Sequence[PollItem[S]], ctx: PollContext) -> Mapping[str, PollOutcome[S]]:
|
|
251
|
+
"""Poll every target of `batch` and return an outcome per target key. A target left out counts as a
|
|
252
|
+
transient error. Raise a :class:`SourceError` when the whole call failed."""
|
|
253
|
+
|
|
254
|
+
def diff(self, target: Target, previous: S, current: S, events: frozenset[str]) -> Sequence[RawEvent]:
|
|
255
|
+
"""The events between two snapshots, limited to `events`: the same pure diff :meth:`poll` uses.
|
|
256
|
+
|
|
257
|
+
The engine calls it when a watcher resubscribes with a baseline (after a daemon restart, a drain or an
|
|
258
|
+
expired lease) to a resource that other watchers keep polling, so this watcher still learns what changed
|
|
259
|
+
in the gap. Default: no events, and the watcher only gets the new snapshot in `watch_started`."""
|
|
260
|
+
return ()
|
|
261
|
+
|
|
262
|
+
def summary(self, target: Target, snapshot: S | None) -> dict[str, Any]:
|
|
263
|
+
"""A compact description of the snapshot, sent in `watch_started`."""
|
|
264
|
+
return {}
|
|
265
|
+
|
|
266
|
+
def encode(self, snapshot: S) -> Any:
|
|
267
|
+
"""The snapshot as JSON. Default: the snapshot is already JSON.
|
|
268
|
+
|
|
269
|
+
Its hash decides when watchers get the snapshot again, so it must not change while the target does not:
|
|
270
|
+
keep fetch times, ETags and other volatile values in `PollItem.state` instead."""
|
|
271
|
+
return snapshot
|
|
272
|
+
|
|
273
|
+
def decode(self, target: Target, data: Any) -> S:
|
|
274
|
+
"""A snapshot from :meth:`encode` (a baseline a watcher kept). Raise `ValueError` when it does not fit."""
|
|
275
|
+
return data # type: ignore[no-any-return]
|
|
276
|
+
|
|
277
|
+
def status(self) -> dict[str, Any]:
|
|
278
|
+
"""What `daemon status` shows about the source, such as request counts per host. Never put params here."""
|
|
279
|
+
return {}
|
|
280
|
+
|
|
281
|
+
def check_options(self, target: Target, options: Mapping[str, Any]) -> Mapping[str, Any]:
|
|
282
|
+
"""Validate the source options a watcher subscribes with, and return them normalized. Raise `ValueError`
|
|
283
|
+
with a message for the watcher when they cannot work. Default: any options are taken as they are."""
|
|
284
|
+
return dict(options)
|
|
285
|
+
|
|
286
|
+
def children(self, target: Target, snapshot: S, item: PollItem[S]) -> Mapping[Target, frozenset[str] | Wants]:
|
|
287
|
+
"""Other targets whose events this one relays, each with the kinds (and options) it wants from them, such as
|
|
288
|
+
an MR that relays its head pipeline. `item` says what the subscribers of `target` want. A child is polled
|
|
289
|
+
as a target of its own, in the parent's account, and its events other than the lifecycle ones go into the
|
|
290
|
+
parent's log too."""
|
|
291
|
+
return {}
|
cli_watch_kit/timers.py
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
"""What a watcher derives from time: the threshold events of the app, and the idle end of a watch.
|
|
2
|
+
|
|
3
|
+
Both come from the snapshots and events the watcher already receives, so they cost no request. The daemon never sees
|
|
4
|
+
them: they depend on what this watcher reported, which differs per watcher of the same resource.
|
|
5
|
+
|
|
6
|
+
An app adds its own threshold kinds (glab's `quiet` and `pipeline_stuck`, for example) as :class:`ClientTimer` objects
|
|
7
|
+
and names their options in the catalog's `thresholds`. :class:`IdleTimer` ends a watch when nothing was reported for
|
|
8
|
+
`--idle-after`; threshold events do not count as activity, so a quiet resource stays idle after `quiet`.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
from collections.abc import Iterable
|
|
14
|
+
from typing import Any, Protocol
|
|
15
|
+
|
|
16
|
+
from cli_watch_kit.durations import format_duration
|
|
17
|
+
from cli_watch_kit.events import Event
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class ClientTimer(Protocol):
|
|
21
|
+
"""An app's threshold event source inside the watcher. The watcher passes a monotonic `now` everywhere."""
|
|
22
|
+
|
|
23
|
+
def snapshot(self, data: Any, now: float) -> None:
|
|
24
|
+
"""Take in a snapshot the daemon sent, as the source encoded it."""
|
|
25
|
+
...
|
|
26
|
+
|
|
27
|
+
def reported(self, events: Iterable[Event], now: float) -> None:
|
|
28
|
+
"""The events the watcher just reported, threshold events included."""
|
|
29
|
+
...
|
|
30
|
+
|
|
31
|
+
def due(self, now: float) -> list[tuple[str, dict[str, Any]]]:
|
|
32
|
+
"""The threshold events due now, as (kind, data). Each should be returned once."""
|
|
33
|
+
...
|
|
34
|
+
|
|
35
|
+
def seconds_until_next(self, now: float) -> float | None:
|
|
36
|
+
"""How long until the next threshold can fire, so the watcher does not sleep past it."""
|
|
37
|
+
...
|
|
38
|
+
|
|
39
|
+
def describe(self) -> str | None:
|
|
40
|
+
"""A part of the header's `thresholds:` line, such as `quiet after 2m`, or `None`."""
|
|
41
|
+
...
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class IdleTimer:
|
|
45
|
+
"""Ends a watch when nothing but threshold events was reported for `idle_after` seconds."""
|
|
46
|
+
|
|
47
|
+
def __init__(self, idle_after: float | None, threshold_kinds: Iterable[str], now: float) -> None:
|
|
48
|
+
self.idle_after = idle_after
|
|
49
|
+
self.threshold_kinds = frozenset(threshold_kinds)
|
|
50
|
+
self._last_activity = now
|
|
51
|
+
|
|
52
|
+
def reported(self, events: Iterable[Event], now: float) -> None:
|
|
53
|
+
if any(e.kind not in self.threshold_kinds for e in events):
|
|
54
|
+
self._last_activity = now
|
|
55
|
+
|
|
56
|
+
def idle(self, now: float) -> bool:
|
|
57
|
+
return self.idle_after is not None and now - self._last_activity >= self.idle_after
|
|
58
|
+
|
|
59
|
+
def seconds_until_next(self, now: float) -> float | None:
|
|
60
|
+
if self.idle_after is None:
|
|
61
|
+
return None
|
|
62
|
+
return max(0.0, self._last_activity + self.idle_after - now)
|
|
63
|
+
|
|
64
|
+
def describe(self) -> str | None:
|
|
65
|
+
if self.idle_after is None:
|
|
66
|
+
return None
|
|
67
|
+
return f"after {format_duration(self.idle_after)} without an event"
|