formist-cli 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.
- formist_cli/__init__.py +1 -0
- formist_cli/__main__.py +3 -0
- formist_cli/airtable.py +238 -0
- formist_cli/alerts.py +207 -0
- formist_cli/api.py +1027 -0
- formist_cli/chat.py +618 -0
- formist_cli/chats.py +517 -0
- formist_cli/cli.py +1367 -0
- formist_cli/cli_support.py +221 -0
- formist_cli/connectors.py +358 -0
- formist_cli/context.py +164 -0
- formist_cli/diff.py +943 -0
- formist_cli/doctor.py +128 -0
- formist_cli/export.py +427 -0
- formist_cli/files.py +670 -0
- formist_cli/importer.py +425 -0
- formist_cli/kb.py +185 -0
- formist_cli/login.py +615 -0
- formist_cli/logs.py +781 -0
- formist_cli/meetings.py +200 -0
- formist_cli/messages.py +414 -0
- formist_cli/participants.py +402 -0
- formist_cli/prefs.py +328 -0
- formist_cli/privileges.py +375 -0
- formist_cli/projects.py +127 -0
- formist_cli/resolve.py +443 -0
- formist_cli/settings.py +199 -0
- formist_cli/skill_library.py +246 -0
- formist_cli/skills.py +308 -0
- formist_cli/space_plan.py +411 -0
- formist_cli/spaces.py +693 -0
- formist_cli/targets.py +153 -0
- formist_cli/textnorm.py +26 -0
- formist_cli/tokens.py +339 -0
- formist_cli/update.py +433 -0
- formist_cli/uploads.py +928 -0
- formist_cli/usage_tokens.py +152 -0
- formist_cli/users.py +384 -0
- formist_cli/whatsapp.py +451 -0
- formist_cli-0.1.0.dist-info/METADATA +176 -0
- formist_cli-0.1.0.dist-info/RECORD +44 -0
- formist_cli-0.1.0.dist-info/WHEEL +4 -0
- formist_cli-0.1.0.dist-info/entry_points.txt +2 -0
- formist_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
formist_cli/logs.py
ADDED
|
@@ -0,0 +1,781 @@
|
|
|
1
|
+
"""``fm logs``: a live subscription to the server's whole event bus.
|
|
2
|
+
|
|
3
|
+
This is a tap, not a log: it shows what the server emits from now on,
|
|
4
|
+
over ``/admin/events/*``. There is no ``--since`` and there cannot be
|
|
5
|
+
one, since no durable event store exists on the server side to replay
|
|
6
|
+
from; for history, use `fm audit-log`, `fm chats` or `fm connectors`
|
|
7
|
+
instead. ``/admin/events`` is served from the Global region only.
|
|
8
|
+
|
|
9
|
+
This command must never invoke the ``az`` CLI, so there is one
|
|
10
|
+
transport and one credential, and it works for anyone with a session
|
|
11
|
+
token and no Azure login at all; a test enforces this structurally.
|
|
12
|
+
|
|
13
|
+
A live firehose is not a log: the event bus is in-process and touches
|
|
14
|
+
no database, so a redeploy resets its counters, and this command can
|
|
15
|
+
never answer what happened at a specific past time.
|
|
16
|
+
|
|
17
|
+
A healthy, quiet stream and a connection that never opened look
|
|
18
|
+
identical, an iterator that is not yielding, so this module keeps
|
|
19
|
+
three things apart deliberately:
|
|
20
|
+
|
|
21
|
+
* a subscription reaches live only once it is handed the server's own
|
|
22
|
+
preamble (:meth:`Subscription.confirm`); nothing renders a
|
|
23
|
+
"connected" line from what the process merely intended to do.
|
|
24
|
+
* ending is a reason, not an absence: :data:`Ended` distinguishes a
|
|
25
|
+
deadline from an interrupt from a server that went away, and each
|
|
26
|
+
gets a different exit code.
|
|
27
|
+
* a stream with no liveness signal is refused up front
|
|
28
|
+
(:func:`require_liveness_signal`): with ``keepalive=0`` a text
|
|
29
|
+
stream puts nothing on the wire while the bus is quiet, and at that
|
|
30
|
+
point idle and dead are indistinguishable.
|
|
31
|
+
|
|
32
|
+
Stdlib only: this module must not add a runtime dependency.
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
from __future__ import annotations
|
|
36
|
+
|
|
37
|
+
import argparse
|
|
38
|
+
import enum
|
|
39
|
+
import json
|
|
40
|
+
import sys
|
|
41
|
+
import time
|
|
42
|
+
from collections.abc import Callable, Iterable, Iterator
|
|
43
|
+
|
|
44
|
+
from formist_cli import api, context
|
|
45
|
+
from formist_cli.cli_support import add_admin_flag
|
|
46
|
+
from formist_cli.cli_support import build_standalone_parser as _build_standalone_parser
|
|
47
|
+
from formist_cli.targets import Target, is_admin_env
|
|
48
|
+
|
|
49
|
+
#: The ``/admin/events/*`` surface.
|
|
50
|
+
SUBJECTS = ("stream", "rates", "jobs", "activity", "types")
|
|
51
|
+
|
|
52
|
+
DEFAULT_SUBJECT = "stream"
|
|
53
|
+
|
|
54
|
+
#: Printed to stderr before a stream starts. The most likely
|
|
55
|
+
#: misreading of this tool is that it is a log, so the correction goes
|
|
56
|
+
#: where the operator is looking, and it names somewhere to go.
|
|
57
|
+
LIVE_ONLY_NOTE = (
|
|
58
|
+
"This is a LIVE tap, not a log: it shows what the server emits from now on.\n"
|
|
59
|
+
" The event bus is in-process and this stream touches no database, so it "
|
|
60
|
+
"cannot tell you what happened yesterday, and rates/jobs/activity are "
|
|
61
|
+
"counters since the last boot.\n"
|
|
62
|
+
" For what already happened: `fm audit-log` (durable, per space), "
|
|
63
|
+
"`fm chats` (an agent run's own transcript), `fm connectors` (the last sync "
|
|
64
|
+
"run per connector). A crash before the first emit() is in none of them."
|
|
65
|
+
)
|
|
66
|
+
|
|
67
|
+
#: What leaves the room when this runs on a shared screen.
|
|
68
|
+
#:
|
|
69
|
+
#: In ``--help`` rather than in a docstring, because the disclosure is
|
|
70
|
+
#: only useful before the command runs.
|
|
71
|
+
STREAM_CARRIES = """WHAT THE STREAM CARRIES: read before sharing your screen
|
|
72
|
+
|
|
73
|
+
REDACTED by the server:
|
|
74
|
+
credentials any key containing password/secret/token/api_key/cookie/jwt/...,
|
|
75
|
+
plus any value shaped like a Bearer JWT, whatever its key
|
|
76
|
+
user content content/body/text/transcript/summary/prompt/args/result/... become a
|
|
77
|
+
SHAPE marker (<str:4210>), never previewed
|
|
78
|
+
|
|
79
|
+
NOT REDACTED. These reach your terminal in full:
|
|
80
|
+
join_url a meeting's join link. This is a CAPABILITY, not a name:
|
|
81
|
+
whoever reads it can enter the meeting. It is not saved by
|
|
82
|
+
an 80-char clip either; a real Teams join URL measured 69
|
|
83
|
+
characters, so it prints ENTIRE, ?p= passcode included.
|
|
84
|
+
A clip is not a redaction.
|
|
85
|
+
author_name the author's display name, or their email address when no
|
|
86
|
+
display name was set, under a key that does not say so.
|
|
87
|
+
subject a meeting's title. name a space's name.
|
|
88
|
+
error/reason 160-char previews of failure detail, URLs and paths included.
|
|
89
|
+
ids project/entity/user/file UUIDs, truncated to 8 chars.
|
|
90
|
+
|
|
91
|
+
This gap is known and intentionally not closed: logs are not redacted
|
|
92
|
+
here, because operators need unredacted output to diagnose issues.
|
|
93
|
+
|
|
94
|
+
So: credentials and message bodies are safe to show. MEETING JOIN LINKS, EMAIL
|
|
95
|
+
ADDRESSES, MEETING TITLES AND SPACE NAMES ARE NOT. Narrow with --types first.
|
|
96
|
+
|
|
97
|
+
Scope, so this is not read as bigger than it is: /admin/events is
|
|
98
|
+
platform-admin-only, and a platform admin can already read space data through
|
|
99
|
+
/admin/*. This is scrollback hygiene, not an authorization boundary."""
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
class LogsError(Exception):
|
|
103
|
+
"""A refusal about the event surface, written for an operator."""
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
# ===========================================================================
|
|
107
|
+
# Subject selection
|
|
108
|
+
# ===========================================================================
|
|
109
|
+
def canonical_subject(subject: str | None) -> str:
|
|
110
|
+
"""Normalise the positional subject. ``None`` means the stream."""
|
|
111
|
+
if subject is None:
|
|
112
|
+
return DEFAULT_SUBJECT
|
|
113
|
+
value = subject.strip().lower()
|
|
114
|
+
if value not in SUBJECTS:
|
|
115
|
+
raise LogsError(
|
|
116
|
+
f"unknown subject {subject!r}. Valid: {', '.join(SUBJECTS)}.\n"
|
|
117
|
+
" stream live firehose\n"
|
|
118
|
+
" rates one-shot rate snapshot\n"
|
|
119
|
+
" jobs per background job: last run, counts, failures\n"
|
|
120
|
+
" activity what is in flight right now\n"
|
|
121
|
+
" types the event-type vocabulary"
|
|
122
|
+
)
|
|
123
|
+
return value
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def subject_path(subject: str) -> str:
|
|
127
|
+
return f"/admin/events/{subject}"
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def require_admin_region(target: Target) -> None:
|
|
131
|
+
"""Refuse an admin call aimed at a prod env that does not serve ``/admin``,
|
|
132
|
+
before sending it.
|
|
133
|
+
|
|
134
|
+
Same rule as :func:`formist_cli.api.admin_get`: ``/admin`` is
|
|
135
|
+
served from the Global region (and, as its own single-region
|
|
136
|
+
deployment, Formist); other regions answer 410. Repeated here
|
|
137
|
+
because the streaming path does not go through ``admin_get``, and
|
|
138
|
+
a rule enforced on one of several callers is a rule the others do
|
|
139
|
+
not have.
|
|
140
|
+
"""
|
|
141
|
+
if target.is_prod and not is_admin_env(target.env):
|
|
142
|
+
raise LogsError(
|
|
143
|
+
f"/admin/events is served from the GLOBAL region only; sending this "
|
|
144
|
+
f"to {target.name} would return 410.\n"
|
|
145
|
+
"Use `--host evane`. The event bus you want is the Global "
|
|
146
|
+
"instance's; a region's own bus is not exposed separately."
|
|
147
|
+
)
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def build_params(
|
|
151
|
+
*,
|
|
152
|
+
types: str | None = None,
|
|
153
|
+
exclude: str | None = None,
|
|
154
|
+
project: str | None = None,
|
|
155
|
+
source: str | None = None,
|
|
156
|
+
only_work: bool = False,
|
|
157
|
+
mode: str | None = None,
|
|
158
|
+
as_json: bool = False,
|
|
159
|
+
interval: int | None = None,
|
|
160
|
+
keepalive: int | None = None,
|
|
161
|
+
) -> dict[str, str]:
|
|
162
|
+
"""Build the query params for ``/admin/events/*``, in the route's vocabulary.
|
|
163
|
+
|
|
164
|
+
Every filter is passed through rather than applied here: filtering
|
|
165
|
+
a stream client-side is worse than filtering a list client-side,
|
|
166
|
+
since a line dropped by the client was never counted anywhere, so
|
|
167
|
+
nothing contradicts the impression that you saw everything.
|
|
168
|
+
|
|
169
|
+
An unset filter is absent, never empty: ``types=""`` is a filter
|
|
170
|
+
matching nothing, which is the opposite of no filter.
|
|
171
|
+
|
|
172
|
+
No credential is ever placed here. The server deliberately refuses
|
|
173
|
+
a ``?token=`` query parameter so the JWT stays out of URLs, access
|
|
174
|
+
logs, proxy logs and shell history; the token travels in the
|
|
175
|
+
Authorization header instead.
|
|
176
|
+
"""
|
|
177
|
+
params: dict[str, str] = {"format": "json" if as_json else "text"}
|
|
178
|
+
if types:
|
|
179
|
+
params["types"] = types
|
|
180
|
+
if exclude:
|
|
181
|
+
params["exclude"] = exclude
|
|
182
|
+
if project:
|
|
183
|
+
params["project_id"] = project
|
|
184
|
+
if source:
|
|
185
|
+
params["source"] = source
|
|
186
|
+
if only_work:
|
|
187
|
+
params["only_work"] = "1"
|
|
188
|
+
if mode:
|
|
189
|
+
params["mode"] = mode
|
|
190
|
+
if interval is not None:
|
|
191
|
+
params["interval"] = str(interval)
|
|
192
|
+
if keepalive is not None:
|
|
193
|
+
params["keepalive"] = str(keepalive)
|
|
194
|
+
return params
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
# ===========================================================================
|
|
198
|
+
# Liveness: the only thing that separates idle from dead
|
|
199
|
+
# ===========================================================================
|
|
200
|
+
#: sse-starlette's fallback ping period on the server: ``ping=max(keepalive or 30, 1)``.
|
|
201
|
+
SSE_PING_FALLBACK = 30
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def require_liveness_signal(keepalive: int, as_json: bool) -> None:
|
|
205
|
+
"""Refuse a text stream that would put nothing on the wire while idle.
|
|
206
|
+
|
|
207
|
+
With ``keepalive=0`` the server's text generator emits no status
|
|
208
|
+
line, so a quiet bus and a dead socket become byte-for-byte
|
|
209
|
+
identical and no amount of care in this file can tell them apart
|
|
210
|
+
afterwards.
|
|
211
|
+
|
|
212
|
+
JSON is deliberately exempt, and this is not laxness: sse-starlette
|
|
213
|
+
pings on its own schedule regardless of the requested keepalive, so
|
|
214
|
+
a JSON stream is never silent.
|
|
215
|
+
"""
|
|
216
|
+
if keepalive == 0 and not as_json:
|
|
217
|
+
raise LogsError(
|
|
218
|
+
"--keepalive 0 is refused for a text stream.\n"
|
|
219
|
+
"With no keepalive the server sends nothing at all while the bus is "
|
|
220
|
+
"quiet, so an idle stream and a dropped connection look identical, "
|
|
221
|
+
"which is the one thing this command exists to prevent.\n"
|
|
222
|
+
"Use a positive --keepalive, or --json (sse-starlette pings on its "
|
|
223
|
+
"own schedule there, so that stream is never silent)."
|
|
224
|
+
)
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def effective_ping(keepalive: int, as_json: bool) -> int:
|
|
228
|
+
"""How often the server promises to put something on the wire, in its own terms."""
|
|
229
|
+
if as_json:
|
|
230
|
+
return max(keepalive or SSE_PING_FALLBACK, 1)
|
|
231
|
+
return keepalive
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
def read_timeout_for(keepalive: int, as_json: bool) -> float:
|
|
235
|
+
"""Socket read timeout: tolerate exactly one missed keepalive, then give up.
|
|
236
|
+
|
|
237
|
+
Derived from the server's period rather than picked here. Too
|
|
238
|
+
short and a healthy idle stream is torn down and reported as a
|
|
239
|
+
drop; too long, or absent, and a dead socket hangs forever looking
|
|
240
|
+
like a quiet one.
|
|
241
|
+
"""
|
|
242
|
+
return effective_ping(keepalive, as_json) * 2 + 5
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
# ===========================================================================
|
|
246
|
+
# The subscription's own state
|
|
247
|
+
# ===========================================================================
|
|
248
|
+
class Phase(enum.Enum):
|
|
249
|
+
OPENING = "opening"
|
|
250
|
+
LIVE = "live"
|
|
251
|
+
ENDED = "ended"
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
class Ended(enum.Enum):
|
|
255
|
+
#: ``--for N`` elapsed. The normal, successful way to stop.
|
|
256
|
+
DEADLINE = "deadline"
|
|
257
|
+
#: Ctrl-C. Also normal.
|
|
258
|
+
INTERRUPTED = "interrupted"
|
|
259
|
+
#: The server or the network went away. Not normal, and not a quiet stream.
|
|
260
|
+
SERVER_CLOSED = "server-closed"
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
class Kind(enum.Enum):
|
|
264
|
+
#: Stream payload, stdout, pipeable.
|
|
265
|
+
OUT = "out"
|
|
266
|
+
#: The subscription talking about itself, stderr, never in the data.
|
|
267
|
+
STATE = "state"
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
OUT = Kind.OUT
|
|
271
|
+
STATE = Kind.STATE
|
|
272
|
+
|
|
273
|
+
#: The two literal shapes of the text preamble.
|
|
274
|
+
#:
|
|
275
|
+
#: Matched on their literal text rather than on "a leading ``#``",
|
|
276
|
+
#: since the keepalive status line also begins with ``#``. A
|
|
277
|
+
#: leading-hash rule would swallow the status line into the handshake
|
|
278
|
+
#: on an idle stream, i.e. the code proving the connection is alive
|
|
279
|
+
#: would eat the one line proving it is alive. If the server ever
|
|
280
|
+
#: changes this banner the handshake stops confirming, which is the
|
|
281
|
+
#: safe direction: "cannot verify what this is connected to" rather
|
|
282
|
+
#: than a silently eaten line.
|
|
283
|
+
BANNER_HEAD = "# evane admin event firehose"
|
|
284
|
+
BANNER_MODE = "# mode="
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
class Subscription:
|
|
288
|
+
"""What this process is listening to, and whether it actually is.
|
|
289
|
+
|
|
290
|
+
Deliberately not a dataclass of plain fields: :attr:`phase` may
|
|
291
|
+
only advance through :meth:`confirm` and :meth:`end`, so "we are
|
|
292
|
+
connected" cannot be set by an assignment somebody adds later in a
|
|
293
|
+
hurry.
|
|
294
|
+
"""
|
|
295
|
+
|
|
296
|
+
def __init__(
|
|
297
|
+
self,
|
|
298
|
+
*,
|
|
299
|
+
env: str,
|
|
300
|
+
api_base: str,
|
|
301
|
+
path: str,
|
|
302
|
+
filters: dict[str, str],
|
|
303
|
+
clock: Callable[[], float] = time.monotonic,
|
|
304
|
+
):
|
|
305
|
+
self.env = env
|
|
306
|
+
self.api_base = api_base
|
|
307
|
+
self.path = path
|
|
308
|
+
self.filters = dict(filters)
|
|
309
|
+
self.phase = Phase.OPENING
|
|
310
|
+
#: The server's own words, read back off the wire. The only
|
|
311
|
+
#: evidence that this subscription exists. ``None`` until it
|
|
312
|
+
#: arrives.
|
|
313
|
+
self.server_preamble: str | None = None
|
|
314
|
+
self.events = 0
|
|
315
|
+
self.status_lines = 0
|
|
316
|
+
self.ended_reason: Ended | None = None
|
|
317
|
+
self.elapsed = 0.0
|
|
318
|
+
self._clock = clock
|
|
319
|
+
self._started = clock()
|
|
320
|
+
|
|
321
|
+
@property
|
|
322
|
+
def confirmed(self) -> bool:
|
|
323
|
+
return self.server_preamble is not None
|
|
324
|
+
|
|
325
|
+
def confirm(self, preamble: str) -> None:
|
|
326
|
+
"""Promote to LIVE using the server's own preamble. The only such path.
|
|
327
|
+
|
|
328
|
+
An empty preamble is refused rather than accepted-and-ignored:
|
|
329
|
+
whitespace is not the server identifying itself, and a
|
|
330
|
+
subscription confirmed by nothing is exactly the state this
|
|
331
|
+
class exists to make unrepresentable.
|
|
332
|
+
"""
|
|
333
|
+
if not preamble or not preamble.strip():
|
|
334
|
+
raise LogsError(
|
|
335
|
+
"the server sent an empty preamble: refusing to report this "
|
|
336
|
+
"connection as live. Nothing identified the deployment, so there "
|
|
337
|
+
"is nothing to trust about what follows."
|
|
338
|
+
)
|
|
339
|
+
if self.phase is Phase.ENDED:
|
|
340
|
+
raise LogsError("cannot confirm a subscription that has already ended")
|
|
341
|
+
self.server_preamble = preamble.strip()
|
|
342
|
+
self.phase = Phase.LIVE
|
|
343
|
+
|
|
344
|
+
def count_event(self) -> None:
|
|
345
|
+
self.events += 1
|
|
346
|
+
|
|
347
|
+
def count_status(self) -> None:
|
|
348
|
+
self.status_lines += 1
|
|
349
|
+
|
|
350
|
+
def end(self, reason: Ended, *, elapsed: float | None = None) -> None:
|
|
351
|
+
self.elapsed = self._clock() - self._started if elapsed is None else elapsed
|
|
352
|
+
self.ended_reason = reason
|
|
353
|
+
self.phase = Phase.ENDED
|
|
354
|
+
|
|
355
|
+
|
|
356
|
+
def _filter_summary(sub: Subscription) -> str:
|
|
357
|
+
shown = {k: v for k, v in sub.filters.items() if k != "format"}
|
|
358
|
+
return " ".join(f"{k}={v}" for k, v in sorted(shown.items())) or "no filters (everything)"
|
|
359
|
+
|
|
360
|
+
|
|
361
|
+
def render_opening(sub: Subscription) -> str:
|
|
362
|
+
"""Printed before the request, so a hang has a visible subject.
|
|
363
|
+
|
|
364
|
+
Everything here is what the client intends; nothing in it may be
|
|
365
|
+
reused to claim the connection succeeded.
|
|
366
|
+
"""
|
|
367
|
+
return (
|
|
368
|
+
f"subscribing to {sub.api_base}{sub.path} [{sub.env}]\n"
|
|
369
|
+
f" {_filter_summary(sub)}\n"
|
|
370
|
+
f" waiting for the server's banner..."
|
|
371
|
+
)
|
|
372
|
+
|
|
373
|
+
|
|
374
|
+
def render_live(sub: Subscription) -> str:
|
|
375
|
+
"""The connected line, built only from what came back off the wire.
|
|
376
|
+
|
|
377
|
+
Refuses on an unconfirmed subscription rather than falling back to
|
|
378
|
+
``sub.api_base``: that fallback would print a confident,
|
|
379
|
+
correct-looking "connected" line for a socket that never produced
|
|
380
|
+
a byte, indistinguishable from a genuine connection.
|
|
381
|
+
"""
|
|
382
|
+
if not sub.confirmed:
|
|
383
|
+
raise LogsError(
|
|
384
|
+
"refusing to render a live line for an unconfirmed subscription: "
|
|
385
|
+
"the server has not identified itself yet. (This is a bug if you "
|
|
386
|
+
"are seeing it: nothing should reach here before the banner.)"
|
|
387
|
+
)
|
|
388
|
+
return f"LIVE: the server says: {sub.server_preamble}"
|
|
389
|
+
|
|
390
|
+
|
|
391
|
+
def render_ended(sub: Subscription) -> str:
|
|
392
|
+
"""How this stopped. Every branch says what the operator now knows.
|
|
393
|
+
|
|
394
|
+
The two zero-event endings must not read alike: a quiet bus and a
|
|
395
|
+
connection that never opened are the same picture at the terminal
|
|
396
|
+
and different facts about the system.
|
|
397
|
+
"""
|
|
398
|
+
seconds = f"{sub.elapsed:.1f}s"
|
|
399
|
+
counted = f"{sub.events} events"
|
|
400
|
+
|
|
401
|
+
if not sub.confirmed:
|
|
402
|
+
return (
|
|
403
|
+
f"NOT LISTENING: after {seconds} the server never sent its banner.\n"
|
|
404
|
+
f" You were not subscribed. This is not a quiet bus: nothing arrived "
|
|
405
|
+
f"at all, not even the deployment header every stream opens with.\n"
|
|
406
|
+
f" Check `fm doctor --host {sub.env}`; if that is healthy, the "
|
|
407
|
+
f"request reached something that is not this API."
|
|
408
|
+
)
|
|
409
|
+
|
|
410
|
+
if sub.ended_reason is Ended.SERVER_CLOSED:
|
|
411
|
+
return (
|
|
412
|
+
f"STREAM CLOSED BY THE SERVER after {seconds} ({counted}).\n"
|
|
413
|
+
f" This is not the same as a quiet stream: you have stopped being "
|
|
414
|
+
f"told anything, and there is no replay, since the bus is "
|
|
415
|
+
f"in-process and buffers nothing for a subscriber that has gone.\n"
|
|
416
|
+
f" Re-run to resubscribe. Events emitted in between are lost."
|
|
417
|
+
)
|
|
418
|
+
|
|
419
|
+
how = "you stopped it" if sub.ended_reason is Ended.INTERRUPTED else "the --for budget elapsed"
|
|
420
|
+
tail = (
|
|
421
|
+
f" The bus was genuinely quiet: {sub.status_lines} keepalives arrived, so "
|
|
422
|
+
f"the connection was live throughout and had nothing to report."
|
|
423
|
+
if sub.events == 0
|
|
424
|
+
else ""
|
|
425
|
+
)
|
|
426
|
+
return (
|
|
427
|
+
f"done after {seconds} ({counted}), {how}.\n"
|
|
428
|
+
f" was listening to: {sub.server_preamble}"
|
|
429
|
+
+ (f"\n{tail}" if tail else "")
|
|
430
|
+
)
|
|
431
|
+
|
|
432
|
+
|
|
433
|
+
def exit_code(sub: Subscription) -> int:
|
|
434
|
+
"""A status the caller can branch on, since the text scrolls away.
|
|
435
|
+
|
|
436
|
+
A dropped connection must not exit 0.
|
|
437
|
+
"""
|
|
438
|
+
if not sub.confirmed:
|
|
439
|
+
return 2
|
|
440
|
+
if sub.ended_reason is Ended.SERVER_CLOSED:
|
|
441
|
+
return 1
|
|
442
|
+
if sub.ended_reason is Ended.INTERRUPTED:
|
|
443
|
+
return 130
|
|
444
|
+
return 0
|
|
445
|
+
|
|
446
|
+
|
|
447
|
+
# ===========================================================================
|
|
448
|
+
# Wire -> operator
|
|
449
|
+
# ===========================================================================
|
|
450
|
+
def parse_sse(lines: Iterable[str]) -> Iterator[dict]:
|
|
451
|
+
"""Turn SSE frames into one record per frame.
|
|
452
|
+
|
|
453
|
+
A line starting with ``:`` is an SSE comment and carries no data;
|
|
454
|
+
sse-starlette's ``ping`` emits exactly that, and passing those
|
|
455
|
+
through would put non-events into a stream whose only purpose is
|
|
456
|
+
being machine-readable.
|
|
457
|
+
|
|
458
|
+
A frame with no terminating blank line is still emitted: a stream
|
|
459
|
+
ends when the connection does, not on a tidy boundary, so
|
|
460
|
+
swallowing the last frame would lose data precisely when something
|
|
461
|
+
went wrong.
|
|
462
|
+
"""
|
|
463
|
+
event: str | None = None
|
|
464
|
+
data: list[str] = []
|
|
465
|
+
|
|
466
|
+
def flush() -> Iterator[dict]:
|
|
467
|
+
nonlocal event, data
|
|
468
|
+
if data:
|
|
469
|
+
raw = "\n".join(data)
|
|
470
|
+
try:
|
|
471
|
+
parsed: object = json.loads(raw)
|
|
472
|
+
except json.JSONDecodeError:
|
|
473
|
+
# Carried as text rather than dropped: the operator can see it was
|
|
474
|
+
# not JSON, where a silent drop just loses a frame.
|
|
475
|
+
parsed = raw
|
|
476
|
+
yield {"event": event or "message", "data": parsed}
|
|
477
|
+
event, data = None, []
|
|
478
|
+
|
|
479
|
+
for raw_line in lines:
|
|
480
|
+
line = raw_line.rstrip("\n")
|
|
481
|
+
if line.startswith(":"):
|
|
482
|
+
continue
|
|
483
|
+
if not line:
|
|
484
|
+
yield from flush()
|
|
485
|
+
continue
|
|
486
|
+
field, _, value = line.partition(":")
|
|
487
|
+
value = value[1:] if value.startswith(" ") else value
|
|
488
|
+
if field == "event":
|
|
489
|
+
event = value
|
|
490
|
+
elif field == "data":
|
|
491
|
+
data.append(value)
|
|
492
|
+
yield from flush()
|
|
493
|
+
|
|
494
|
+
|
|
495
|
+
def consume(
|
|
496
|
+
sub: Subscription, lines: Iterable[str], *, as_json: bool = False
|
|
497
|
+
) -> Iterator[tuple[Kind, str]]:
|
|
498
|
+
"""Drive ``sub`` over ``lines``, yielding ``(kind, text)``.
|
|
499
|
+
|
|
500
|
+
Tagged rather than printed so the whole path is testable without
|
|
501
|
+
capturing a terminal, and so the caller decides which stream each
|
|
502
|
+
kind goes to: payload on stdout (pipeable), the subscription
|
|
503
|
+
talking about itself on stderr (never in the data).
|
|
504
|
+
|
|
505
|
+
Neither ``ready``/``status`` frames nor ``#`` status lines count
|
|
506
|
+
as events. They are the connection describing itself, and counting
|
|
507
|
+
them would make a perfectly idle stream report activity, the
|
|
508
|
+
mirror image of the defect this command is built around.
|
|
509
|
+
"""
|
|
510
|
+
if as_json:
|
|
511
|
+
yield from _consume_json(sub, lines)
|
|
512
|
+
else:
|
|
513
|
+
yield from _consume_text(sub, lines)
|
|
514
|
+
|
|
515
|
+
|
|
516
|
+
def _consume_text(sub: Subscription, lines: Iterable[str]) -> Iterator[tuple[Kind, str]]:
|
|
517
|
+
banner: list[str] = []
|
|
518
|
+
for line in lines:
|
|
519
|
+
if sub.phase is Phase.OPENING:
|
|
520
|
+
if line.startswith(BANNER_HEAD):
|
|
521
|
+
banner.append(line)
|
|
522
|
+
continue
|
|
523
|
+
if banner and line.startswith(BANNER_MODE):
|
|
524
|
+
banner.append(line)
|
|
525
|
+
sub.confirm("\n".join(banner))
|
|
526
|
+
yield (STATE, render_live(sub))
|
|
527
|
+
continue
|
|
528
|
+
if banner:
|
|
529
|
+
# A banner head with no mode line: confirm on what did arrive
|
|
530
|
+
# rather than discard it, then fall through and treat this line as
|
|
531
|
+
# ordinary traffic.
|
|
532
|
+
sub.confirm("\n".join(banner))
|
|
533
|
+
yield (STATE, render_live(sub))
|
|
534
|
+
if line.startswith("#"):
|
|
535
|
+
sub.count_status()
|
|
536
|
+
yield (STATE, line)
|
|
537
|
+
continue
|
|
538
|
+
sub.count_event()
|
|
539
|
+
yield (OUT, line)
|
|
540
|
+
|
|
541
|
+
|
|
542
|
+
def _consume_json(sub: Subscription, lines: Iterable[str]) -> Iterator[tuple[Kind, str]]:
|
|
543
|
+
for record in parse_sse(lines):
|
|
544
|
+
name = record.get("event")
|
|
545
|
+
if name == "ready" and sub.phase is Phase.OPENING:
|
|
546
|
+
sub.confirm(_render_ready(record.get("data")))
|
|
547
|
+
yield (STATE, render_live(sub))
|
|
548
|
+
continue
|
|
549
|
+
if name == "status":
|
|
550
|
+
sub.count_status()
|
|
551
|
+
yield (STATE, json.dumps(record, ensure_ascii=False, sort_keys=True))
|
|
552
|
+
continue
|
|
553
|
+
sub.count_event()
|
|
554
|
+
yield (OUT, json.dumps(record, ensure_ascii=False, sort_keys=True))
|
|
555
|
+
|
|
556
|
+
|
|
557
|
+
def _render_ready(data: object) -> str:
|
|
558
|
+
"""Render the ``ready`` frame's deployment identity as one line.
|
|
559
|
+
|
|
560
|
+
Serialised from the frame rather than composed from what was asked
|
|
561
|
+
for: the key names in the output are the server's, so a reader can
|
|
562
|
+
tell this came off the wire.
|
|
563
|
+
"""
|
|
564
|
+
if isinstance(data, dict):
|
|
565
|
+
deployment = data.get("deployment")
|
|
566
|
+
if isinstance(deployment, dict) and deployment:
|
|
567
|
+
body = " ".join(f"{k}={v}" for k, v in sorted(deployment.items()))
|
|
568
|
+
since = data.get("events_since_boot")
|
|
569
|
+
tail = f", {since} events since boot" if since is not None else ""
|
|
570
|
+
return f"ready: {body}{tail}"
|
|
571
|
+
return json.dumps(data, ensure_ascii=False, sort_keys=True)
|
|
572
|
+
|
|
573
|
+
|
|
574
|
+
def follow(
|
|
575
|
+
lines: Iterable[str],
|
|
576
|
+
*,
|
|
577
|
+
stop_after: float | None = None,
|
|
578
|
+
clock: Callable[[], float] = time.monotonic,
|
|
579
|
+
on_expire: Callable[[], None] | None = None,
|
|
580
|
+
) -> Iterator[str]:
|
|
581
|
+
"""Yield ``lines`` until ``stop_after`` seconds have passed.
|
|
582
|
+
|
|
583
|
+
The clock is injected so the bound can be tested without waiting.
|
|
584
|
+
|
|
585
|
+
``stop_after=0`` stops immediately and is not treated as
|
|
586
|
+
unbounded: falsy-vs-``None`` is exactly where a bound silently
|
|
587
|
+
becomes no bound.
|
|
588
|
+
|
|
589
|
+
``on_expire`` fires only when the deadline stopped this, never
|
|
590
|
+
when the input ran out: one is success and one is a dropped
|
|
591
|
+
connection, and from outside a generator they look identical.
|
|
592
|
+
|
|
593
|
+
The check happens per arriving line, so ``--for N`` fires within
|
|
594
|
+
one keepalive period of N, not at N exactly. That is inherent to a
|
|
595
|
+
blocking iterator, and it is a second reason ``--keepalive 0`` is
|
|
596
|
+
refused: with no keepalive there is no next line to check the
|
|
597
|
+
clock on.
|
|
598
|
+
"""
|
|
599
|
+
if stop_after is None:
|
|
600
|
+
yield from lines
|
|
601
|
+
return
|
|
602
|
+
deadline = clock() + stop_after
|
|
603
|
+
for line in lines:
|
|
604
|
+
if clock() >= deadline:
|
|
605
|
+
if on_expire is not None:
|
|
606
|
+
on_expire()
|
|
607
|
+
return
|
|
608
|
+
yield line
|
|
609
|
+
|
|
610
|
+
|
|
611
|
+
# ===========================================================================
|
|
612
|
+
# CLI
|
|
613
|
+
# ===========================================================================
|
|
614
|
+
_HELP = "live tap on the server's whole event bus (admin, Global-only)"
|
|
615
|
+
|
|
616
|
+
_DESCRIPTION = """Subscribe to the server's event bus and print what it emits, live.
|
|
617
|
+
|
|
618
|
+
This is a tap, not a log. It shows what happens from now on; nothing here can
|
|
619
|
+
tell you what happened yesterday. The bus is in-process and touches no
|
|
620
|
+
database, so nothing is buffered and there is no --since to give you; for
|
|
621
|
+
history use `fm audit-log`, `fm chats` or `fm connectors`.
|
|
622
|
+
|
|
623
|
+
/admin/events is served from the Global region only; --env ae answers 410 and
|
|
624
|
+
is refused before sending.
|
|
625
|
+
|
|
626
|
+
Subjects:
|
|
627
|
+
stream (default) the live firehose
|
|
628
|
+
rates one-shot: what is this server repeating right now
|
|
629
|
+
jobs one-shot: per background job, last run, counts, failures, no-ops
|
|
630
|
+
activity one-shot: what is in flight right now, plus outbound-call counters
|
|
631
|
+
types one-shot: the event-type vocabulary, for filling in --types
|
|
632
|
+
"""
|
|
633
|
+
|
|
634
|
+
|
|
635
|
+
def _add_arguments(parser: argparse.ArgumentParser) -> None:
|
|
636
|
+
parser.add_argument(
|
|
637
|
+
"subject",
|
|
638
|
+
nargs="?",
|
|
639
|
+
help=f"one of: {', '.join(SUBJECTS)} (default: {DEFAULT_SUBJECT})",
|
|
640
|
+
)
|
|
641
|
+
parser.add_argument(
|
|
642
|
+
"--host",
|
|
643
|
+
default=argparse.SUPPRESS,
|
|
644
|
+
metavar="HOST",
|
|
645
|
+
help="deployment name or API origin (default: formist, or `fm use` for reads); "
|
|
646
|
+
"a write never inherits it",
|
|
647
|
+
)
|
|
648
|
+
parser.add_argument("--types", help="CSV of event types; 'on_meeting_*' and '@background' allowed")
|
|
649
|
+
parser.add_argument("--exclude", help="CSV of event types to drop (same glob rules)")
|
|
650
|
+
parser.add_argument("--space", help="only this space's events (UUID)")
|
|
651
|
+
parser.add_argument("--source", help="CSV: scheduler,api,webhook,internal")
|
|
652
|
+
parser.add_argument(
|
|
653
|
+
"--work-only",
|
|
654
|
+
action="store_true",
|
|
655
|
+
help="hide ticks that ran but moved nothing",
|
|
656
|
+
)
|
|
657
|
+
parser.add_argument(
|
|
658
|
+
"--mode",
|
|
659
|
+
choices=("raw", "digest", "both", "jobs", "activity"),
|
|
660
|
+
default=None,
|
|
661
|
+
help="stream shape (default: raw); digest catches a repeating loop raw lines cannot show",
|
|
662
|
+
)
|
|
663
|
+
parser.add_argument("--json", action="store_true", help="SSE JSON records instead of text lines")
|
|
664
|
+
parser.add_argument(
|
|
665
|
+
"--for",
|
|
666
|
+
dest="for_seconds",
|
|
667
|
+
type=float,
|
|
668
|
+
default=None,
|
|
669
|
+
help="stop after N seconds (fires on the next line, so within one keepalive of N)",
|
|
670
|
+
)
|
|
671
|
+
parser.add_argument(
|
|
672
|
+
"--keepalive",
|
|
673
|
+
type=int,
|
|
674
|
+
default=30,
|
|
675
|
+
help=(
|
|
676
|
+
"server status-line period, seconds. 0 is refused for a text stream: "
|
|
677
|
+
"with nothing on the wire, idle and dropped are indistinguishable"
|
|
678
|
+
),
|
|
679
|
+
)
|
|
680
|
+
parser.add_argument("--interval", type=int, default=None, help="digest/jobs emit period, seconds")
|
|
681
|
+
|
|
682
|
+
|
|
683
|
+
def add_parser(subparsers) -> argparse.ArgumentParser:
|
|
684
|
+
"""Register ``fm logs``."""
|
|
685
|
+
parser = subparsers.add_parser(
|
|
686
|
+
"logs",
|
|
687
|
+
help=_HELP,
|
|
688
|
+
description=_DESCRIPTION,
|
|
689
|
+
epilog=STREAM_CARRIES,
|
|
690
|
+
formatter_class=argparse.RawDescriptionHelpFormatter,
|
|
691
|
+
)
|
|
692
|
+
_add_arguments(parser)
|
|
693
|
+
add_admin_flag(parser)
|
|
694
|
+
return parser
|
|
695
|
+
|
|
696
|
+
|
|
697
|
+
def build_standalone_parser() -> argparse.ArgumentParser:
|
|
698
|
+
"""The same parser, detached, so ``--help`` can be rendered in a test."""
|
|
699
|
+
return _build_standalone_parser(add_parser)
|
|
700
|
+
|
|
701
|
+
|
|
702
|
+
def run(args) -> int:
|
|
703
|
+
"""Resolve the target, subscribe, and report honestly."""
|
|
704
|
+
subject = canonical_subject(getattr(args, "subject", None))
|
|
705
|
+
as_json = bool(getattr(args, "json", False))
|
|
706
|
+
keepalive = int(getattr(args, "keepalive", 30))
|
|
707
|
+
require_liveness_signal(keepalive, as_json)
|
|
708
|
+
|
|
709
|
+
ctx = context.resolve(args, need_token=True)
|
|
710
|
+
target = ctx.target
|
|
711
|
+
require_admin_region(target)
|
|
712
|
+
token = ctx.token
|
|
713
|
+
assert token is not None # need_token=True guarantees it; narrows for pyright
|
|
714
|
+
|
|
715
|
+
params = build_params(
|
|
716
|
+
types=getattr(args, "types", None),
|
|
717
|
+
exclude=getattr(args, "exclude", None),
|
|
718
|
+
project=ctx.space,
|
|
719
|
+
source=getattr(args, "source", None),
|
|
720
|
+
only_work=bool(getattr(args, "work_only", False)),
|
|
721
|
+
mode=getattr(args, "mode", None),
|
|
722
|
+
as_json=as_json,
|
|
723
|
+
interval=getattr(args, "interval", None),
|
|
724
|
+
keepalive=keepalive if subject == "stream" else None,
|
|
725
|
+
)
|
|
726
|
+
|
|
727
|
+
if subject != "stream":
|
|
728
|
+
# The one-shot views are a plain GET; there is no subscription to be
|
|
729
|
+
# ambiguous about, so none of the machinery above applies.
|
|
730
|
+
body = api.get(target, subject_path(subject), token=token, params=params)
|
|
731
|
+
print(body if isinstance(body, str) else json.dumps(body, indent=2, ensure_ascii=False))
|
|
732
|
+
return 0
|
|
733
|
+
|
|
734
|
+
print(LIVE_ONLY_NOTE, file=sys.stderr)
|
|
735
|
+
return _run_stream(target, subject_path(subject), token=token, params=params,
|
|
736
|
+
as_json=as_json, keepalive=keepalive,
|
|
737
|
+
for_seconds=getattr(args, "for_seconds", None))
|
|
738
|
+
|
|
739
|
+
|
|
740
|
+
def _run_stream(
|
|
741
|
+
target: Target,
|
|
742
|
+
path: str,
|
|
743
|
+
*,
|
|
744
|
+
token: str,
|
|
745
|
+
params: dict[str, str],
|
|
746
|
+
as_json: bool,
|
|
747
|
+
keepalive: int,
|
|
748
|
+
for_seconds: float | None,
|
|
749
|
+
) -> int:
|
|
750
|
+
sub = Subscription(env=target.env, api_base=target.api_base, path=path, filters=params)
|
|
751
|
+
print(render_opening(sub), file=sys.stderr)
|
|
752
|
+
|
|
753
|
+
hit_deadline = False
|
|
754
|
+
|
|
755
|
+
def expired() -> None:
|
|
756
|
+
nonlocal hit_deadline
|
|
757
|
+
hit_deadline = True
|
|
758
|
+
|
|
759
|
+
try:
|
|
760
|
+
with api.stream(
|
|
761
|
+
target, path, token=token, params=params,
|
|
762
|
+
read_timeout=read_timeout_for(keepalive, as_json),
|
|
763
|
+
) as lines:
|
|
764
|
+
bounded = follow(lines, stop_after=for_seconds, on_expire=expired)
|
|
765
|
+
for kind, text in consume(sub, bounded, as_json=as_json):
|
|
766
|
+
if kind is OUT:
|
|
767
|
+
print(text, flush=True)
|
|
768
|
+
else:
|
|
769
|
+
print(text, file=sys.stderr, flush=True)
|
|
770
|
+
except KeyboardInterrupt:
|
|
771
|
+
sub.end(Ended.INTERRUPTED)
|
|
772
|
+
except api.StreamClosed as exc:
|
|
773
|
+
# Loud, and distinct from a quiet stream: the transport already knows this
|
|
774
|
+
# was not a tidy end, so do not let it arrive as a plain iterator stop.
|
|
775
|
+
print(f"error: {exc}", file=sys.stderr)
|
|
776
|
+
sub.end(Ended.SERVER_CLOSED)
|
|
777
|
+
else:
|
|
778
|
+
sub.end(Ended.DEADLINE if hit_deadline else Ended.SERVER_CLOSED)
|
|
779
|
+
|
|
780
|
+
print(render_ended(sub), file=sys.stderr)
|
|
781
|
+
return exit_code(sub)
|