taskops-cli 0.2.0__py3-none-any.whl

taskops/transports/http/_handler.py

@@ -0,0 +1,132 @@
+"""The request handler: the ONLY file in the package that knows about HTTP.
+
+Split from `server` by what each one does — that module constructs a server, this one answers a
+request. Nothing here decides anything: it parses a `Request`, hands it to the route table, and
+writes back a `Reply`.
+
+Threaded and not async, which is what makes both live transports work: one connection is one thread
+parked in a generator, so the synchronous engine underneath never learns that a stream exists.
+"""
+
+from __future__ import annotations
+
+import socket
+from contextlib import closing
+from http.server import BaseHTTPRequestHandler
+from typing import Any
+from urllib.parse import parse_qsl, urlsplit
+
+from ._wire import Reply, Request, Route
+
+__all__ = ["Handler", "MAX_BODY"]
+
+MAX_BODY = 8 << 20
+"""8 MB. Reading a declared length into memory before checking it is how a small server becomes a
+target, so there is a ceiling at all; it is this high because replication pushes whole documents —
+a batch of 500 events, or `all.md`, which is every day of a project in one file.
+
+The cap TRUNCATES rather than refuses, which is survivable only because everything above it is
+JSON: a truncated body fails to parse and the endpoint answers 400 for a body it cannot read."""
+
+
+class Handler(BaseHTTPRequestHandler):
+    dispatch: Route
+    protocol_version = "HTTP/1.1"
+    """1.1 for keep-alive, which SSE needs. It also obliges every reply to carry an accurate
+    Content-Length — `_send` does, and a streamed reply omits it deliberately."""
+
+    def do_GET(self) -> None:                                        # noqa: N802 — stdlib name
+        self._handle()
+
+    def do_POST(self) -> None:                                       # noqa: N802
+        self._handle()
+
+    def do_PUT(self) -> None:                                        # noqa: N802
+        """Replication pushes a report file. Without this the stdlib answers 501 and the route
+        table's own 405 — the one that tells a caller which methods a path takes — is never
+        reached, so the endpoint would look absent rather than unsupported."""
+        self._handle()
+
+    def log_message(self, format: str, *args: Any) -> None:
+        """Silent. The default logs every request to stderr, which buries the one line the studio
+        prints — the URL a person needs — under a scrolling access log of its own polling."""
+        return
+
+    def handle_error(self, *args: Any) -> None:
+        """A client that disconnects is NOT an error, and socketserver prints a traceback for it.
+
+        Closing a tab resets a keep-alive connection, so the default behaviour puts a ten-line
+        traceback on the console every time somebody closes the board. Everything that IS an error
+        is already caught in `_handle` and answered with a 500.
+        """
+        return
+
+    def _handle(self) -> None:
+        try:
+            reply = type(self).dispatch(self._request())
+        except Exception as err:                       # noqa: BLE001 — a handler must not die
+            # A raised handler kills the thread and the browser sees a dropped connection with no
+            # explanation. One 500 with the exception text is worth far more than a clean stack in
+            # a log nobody is reading.
+            self._send(Reply(status=500, body=f"{type(err).__name__}: {err}".encode()))
+            return
+        self._send(reply)
+
+    def _request(self) -> Request:
+        parts = urlsplit(self.path)
+        length = min(int(self.headers.get("Content-Length") or 0), MAX_BODY)
+        return Request(method=self.command, path=parts.path,
+                       query=dict(parse_qsl(parts.query)),
+                       headers={k.lower(): v for k, v in self.headers.items()},
+                       body=self.rfile.read(length) if length else b"")
+
+    def _send(self, reply: Reply) -> None:
+        """Headers, then either a body or a stream."""
+        self._status(reply.status)
+        for name, value in reply.headers.items():
+            self.send_header(name, value)
+        if reply.stream is None:
+            self.send_header("Content-Length", str(len(reply.body)))
+            self.end_headers()
+            self.wfile.write(reply.body)
+            return
+        self.end_headers()
+        self._pump(reply)
+
+    def _status(self, status: int) -> None:
+        """A 101 upgrade needs different treatment from every other status.
+
+        `send_response_only`, because `send_response` appends `Server` and `Date` — tolerated on a
+        handshake, but not what a websocket client is promised. And `close_connection`, which is the
+        part that matters: after an upgrade this socket is no longer HTTP, so the handler must not try
+        to parse another request off it when the stream ends.
+        """
+        if status == 101:
+            self.send_response_only(101)
+            self.close_connection = True
+            return
+        self.send_response(status)
+
+    def _pump(self, reply: Reply) -> None:
+        """Write frames until the client disconnects, then CLOSE the generator.
+
+        The broken-pipe catch is not defensive noise: closing a tab is the normal way an SSE
+        response ends, so it must be an ordinary return rather than a traceback per closed tab.
+        `flush` after every frame is what makes it live instead of buffered.
+
+        The explicit `close()` is the important line, and it was measured into existence. A streamed
+        body holds a sqlite connection and an event-bus subscription, released by the generator's
+        own `finally` — but on a broken pipe the exception's traceback forms a reference cycle
+        through this frame, so refcounting does not reclaim the generator and the cyclic collector
+        gets to it whenever it likes. Subscriptions were still alive seven seconds after the client
+        hung up. `closing()` runs that `finally` now, deterministically.
+        """
+        if reply.stream is None:
+            return
+        with closing(reply.stream()) as frames:
+            try:
+                for chunk in frames:
+                    self.wfile.write(chunk)
+                    self.wfile.flush()
+            except (BrokenPipeError, ConnectionResetError, socket.timeout):
+                return

taskops/transports/http/_wire.py

@@ -0,0 +1,79 @@
+"""A request and a reply, as data. The whole point of this module is testability.
+
+Every route is a pure function `Request -> Reply`, so the routing table, the policy and each
+endpoint can be tested by calling them — no socket, no thread, no port. The stdlib handler in
+`server` is then the only thing that knows about HTTP at all, and it is the one piece with no
+decisions in it.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Generator
+from dataclasses import dataclass, field
+from typing import Any, Callable, cast
+
+__all__ = ["Request", "Reply", "Route", "json_reply", "error_reply", "Streamer"]
+
+Streamer = Callable[[], Generator[bytes, None, None]]
+"""A reply body produced lazily, for the SSE stream. Called by the server AFTER the headers are
+flushed, which is what lets one response stay open for an hour.
+
+`Generator` and not `Iterator`, deliberately: the server must be able to `close()` it. A streamed
+body holds a database connection and an event-bus subscription, and leaving those to the garbage
+collector is a leak — the traceback of a broken pipe forms a reference cycle, so refcounting does
+not reclaim it and the cyclic collector runs whenever it feels like it. That was measured, not
+assumed: subscriptions survived seven seconds after the client hung up."""
+
+
+@dataclass(frozen=True, slots=True)
+class Request:
+    method: str
+    path: str
+    query: dict[str, str]
+    headers: dict[str, str]
+    body: bytes = b""
+
+    def param(self, name: str, default: str = "") -> str:
+        return self.query.get(name, default)
+
+    def payload(self) -> dict[str, Any]:
+        """The JSON body, or {} — never an exception.
+
+        The caller is a browser we wrote, but also anything a curious person points at the
+        port, and a malformed body has to be a 400 from the endpoint's own validation rather
+        than a traceback from the parser.
+        """
+        if not self.body:
+            return {}
+        try:
+            parsed: object = json.loads(self.body)
+        except json.JSONDecodeError:
+            return {}
+        return cast("dict[str, Any]", parsed) if isinstance(parsed, dict) else {}
+
+
+@dataclass(frozen=True, slots=True)
+class Reply:
+    status: int = 200
+    body: bytes = b""
+    headers: dict[str, str] = field(default_factory=dict[str, str])
+    stream: Streamer | None = None
+    """Set instead of `body` for a response that never ends. The server checks this first."""
+
+
+Route = Callable[[Request], Reply]
+
+
+def json_reply(payload: object, status: int = 200) -> Reply:
+    """`default=str` on purpose: a contract is dicts, lists, strings and floats, and anything
+    else appearing here is a bug better shown as a string in the UI than a 500 with no clue."""
+    return Reply(status=status,
+                 body=json.dumps(payload, default=str).encode("utf-8"),
+                 headers={"Content-Type": "application/json; charset=utf-8"})
+
+
+def error_reply(status: int, message: str, code: str = "error") -> Reply:
+    """One error shape, everywhere. The UI reads `error` and `code`, so a failure renders as a
+    sentence a person can act on rather than a red box with a status number in it."""
+    return json_reply({"error": message, "code": code}, status)

taskops/transports/http/_wsframes.py

@@ -0,0 +1,116 @@
+"""RFC 6455 framing: bytes in, bytes out. No HTTP, no sockets, no state.
+
+Split from `websocket` by concern — that module turns an HTTP request into a socket, this one is the
+binary protocol that flows afterwards. Pure functions over bytes, so every boundary condition below
+is testable from a literal.
+
+Hand-rolled rather than taking the `websockets` library, and the reason is architectural: that
+library is asyncio, and this engine is synchronous by an enforced invariant. Adopting it would mean
+an event loop, a threadpool bridge, and a second concurrency model inside a package whose whole
+storage story is "sqlite, synchronously" — and it would be the first runtime dependency in a package
+that installs into every agent's environment on every machine.
+
+What is deliberately NOT here: outgoing fragmentation (taskops frames are a few hundred bytes),
+extensions, and `permessage-deflate`.
+"""
+
+from __future__ import annotations
+
+import struct
+from typing import BinaryIO
+
+__all__ = ["text_frame", "close_frame", "ping_frame", "read_frame",
+           "OPCODE_TEXT", "OPCODE_CLOSE", "OPCODE_PING", "OPCODE_PONG"]
+
+OPCODE_TEXT = 0x1
+OPCODE_CLOSE = 0x8
+OPCODE_PING = 0x9
+OPCODE_PONG = 0xA
+
+_MAX_PAYLOAD = 1 << 20
+"""1 MB per incoming frame. The client only ever sends pings and closes here, so anything large is a
+mistake or a probe — and reading a declared length into memory before checking it is the classic way
+a small server becomes a denial-of-service target."""
+
+def text_frame(payload: str) -> bytes:
+    """One unfragmented text frame, unmasked.
+
+    A server MUST NOT mask (RFC 6455 §5.1) — a masked server frame is a protocol error and browsers
+    close the connection on it, which reads as a mysteriously dropped socket.
+    """
+    body = payload.encode("utf-8")
+    return _header(OPCODE_TEXT, len(body)) + body
+
+
+def close_frame(code: int = 1000) -> bytes:
+    """A clean close. Sending one before hanging up is what makes the browser's `onclose` carry a
+    normal code instead of 1006, which is the code that means "we have no idea what happened"."""
+    return _header(OPCODE_CLOSE, 2) + struct.pack("!H", code)
+
+
+def ping_frame() -> bytes:
+    """An empty ping. The protocol's OWN liveness probe, and unlike a comment on an SSE stream it
+    gets an answer — so a browser can tell a live-but-idle board from a dead socket."""
+    return _header(OPCODE_PING, 0)
+
+
+def _header(opcode: int, length: int) -> bytes:
+    """FIN set, no mask, and the three length encodings RFC 6455 defines.
+
+    The boundaries are exact and unforgiving: 125 inclusive for the short form, 126 as the marker for
+    a 16-bit length, 127 for 64-bit. An off-by-one here produces a frame a browser silently discards.
+    """
+    first = 0x80 | opcode
+    if length < 126:
+        return struct.pack("!BB", first, length)
+    if length < (1 << 16):
+        return struct.pack("!BBH", first, 126, length)
+    return struct.pack("!BBQ", first, 127, length)
+
+
+def read_frame(stream: BinaryIO) -> tuple[int, bytes] | None:
+    """One incoming frame as `(opcode, payload)`, or None when the stream ends.
+
+    Client frames are always masked, and the mask is applied by XOR with a repeating 4-byte key.
+    Unmasking is not optional: without it a ping's payload comes back as noise and the pong we send
+    would not match, which some clients treat as a failed connection.
+    """
+    head = _exactly(stream, 2)
+    if head is None:
+        return None
+    opcode = head[0] & 0x0F
+    masked = bool(head[1] & 0x80)
+    length = head[1] & 0x7F
+    if length == 126:
+        extended = _exactly(stream, 2)
+        length = struct.unpack("!H", extended)[0] if extended else 0
+    elif length == 127:
+        extended = _exactly(stream, 8)
+        length = struct.unpack("!Q", extended)[0] if extended else 0
+    if length > _MAX_PAYLOAD:
+        return OPCODE_CLOSE, b""
+    mask = _exactly(stream, 4) if masked else b""
+    payload = _exactly(stream, length) if length else b""
+    if payload is None or (masked and mask is None):
+        return None
+    return opcode, _unmask(payload, mask) if masked and mask else payload
+
+
+def _unmask(payload: bytes, mask: bytes) -> bytes:
+    return bytes(byte ^ mask[i % 4] for i, byte in enumerate(payload))
+
+
+def _exactly(stream: BinaryIO, count: int) -> bytes | None:
+    """Read exactly `count` bytes, or None if the stream ended first.
+
+    A loop rather than one `read(count)`: a socket read is allowed to return fewer bytes than asked
+    for, and treating a short read as a complete frame is the bug that makes a websocket work
+    perfectly on localhost and corrupt frames over a real network.
+    """
+    out = b""
+    while len(out) < count:
+        chunk = stream.read(count - len(out))
+        if not chunk:
+            return None
+        out += chunk
+    return out

taskops/transports/http/agentapi.py

@@ -0,0 +1,69 @@
+"""The two writes an AGENT makes, served for agents on other machines.
+
+Its own module for the same reason `exchange.py` is one: the caller here is another taskops,
+not the board's browser, so these shapes are a contract a client codes against
+(`docs/exchange.md`) rather than something the UI and the server can rename together.
+
+Why they exist: a claim is only atomic inside one database. Two agents on two machines each
+claim in their own sqlite and discover the collision at the next sync, which is too late —
+by then both have edited the same files. Routing the write here makes the two claims two
+INSERTs on one primary key in one store, which is a race the engine already wins.
+
+**`local=True` on every call, without exception.** These functions run the same use cases a
+client runs, and those use cases route to the remote when the project has one. A server whose
+store carried a `remote.json` would therefore POST to itself, and answer its own POST by
+POSTing again. The flag is the cycle breaker and it is passed here, at the only place that
+can know it is already the destination.
+
+**The actor is TAKEN FROM THE BODY, and that is a real trust decision.** Everywhere else on
+this server — `post_comment` — the actor is resolved server-side, because a browser naming
+its own actor could post as somebody else's agent. It cannot work that way here: the server
+has neither the remote machine's `$TASKOPS_ACTOR` nor its git config, so it has no way to
+learn who is calling. The project TOKEN is therefore the trust boundary: whoever holds it may
+act as any actor in the project. That is the same boundary git already draws — whoever can
+push to the repository can author a commit under any name — and it is stated here rather than
+buried, because a reader deciding where to put this server deserves to know it. What is still
+enforced is the SHAPE: a malformed id is refused with a 400 by `identity.parse` inside the use
+case, so a typo cannot conjure a ghost identity that half an agent's work then files under.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ...usecases import next_task, update
+from ._wire import Reply, Request, error_reply, json_reply
+from .api import guarded, strings
+
+__all__ = ["post_next", "post_update"]
+
+
+def post_next(root: Path, request: Request) -> Reply:
+    """Claim, decided here. Returns the `NextResult` TypedDict, which is already JSON."""
+    payload = request.payload()
+    actor = str(payload.get("actor", "")).strip()
+    if not actor:
+        return error_reply(400, "`actor` is required — this server cannot infer the identity "
+                                "of an agent on another machine", "bad_request")
+    return guarded(lambda: json_reply(next_task(
+        root, actor=actor, session=str(payload.get("session", "")),
+        labels=strings(payload, "labels"), task=str(payload.get("task", "")), local=True)))
+
+
+def post_update(root: Path, request: Request) -> Reply:
+    """A transition, a comment and a notification — checked by THIS store's guards.
+
+    Which is the point: the lease that `done` requires, and the commits bound to the task, are
+    read from the database every machine writes to, so an agent cannot close a card whose
+    lease it lost to somebody else while its own board was stale.
+    """
+    payload = request.payload()
+    task_id = str(payload.get("task", "")).strip()
+    actor = str(payload.get("actor", "")).strip()
+    if not task_id or not actor:
+        return error_reply(400, "`task` and `actor` are required", "bad_request")
+    return guarded(lambda: json_reply(update(
+        root, task_id, actor=actor, status=str(payload.get("status", "")),
+        comment=str(payload.get("comment", "")), mentions=strings(payload, "mentions"),
+        blocked_on=str(payload.get("blocked_on", "")),
+        no_code=bool(payload.get("no_code")), local=True)))

taskops/transports/http/api.py

@@ -0,0 +1,122 @@
+"""The JSON endpoints. Each one is a use case call and a serialisation, and nothing else.
+
+The contracts ARE the wire format: they are TypedDicts, so at runtime they are already the dicts
+the browser receives, and `studio/src/contracts.ts` mirrors them by hand. That is why there is
+no schema layer here — there is nothing to translate.
+
+Every endpoint takes the repository root as its first argument rather than reading module state.
+The server binds it once (`router.build`), which keeps these functions callable from a test with
+a `tmp_path` and no port open.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, cast
+
+from ..._errors import TaskopsError
+from ..._version import __version__
+from ...usecases import activity, ask, board, fleet, search, standup, update
+from ...usecases.report import HISTORY_WINDOW
+from ._wire import Reply, Request, error_reply, json_reply
+
+__all__ = ["config", "get_board", "get_fleet", "get_standup", "get_task", "get_search",
+           "get_activity", "post_comment", "post_status", "guarded", "strings"]
+
+
+def config(root: Path, request: Request) -> Reply:
+    """What the UI needs before its first render. Sent once, so the board does not have to
+    discover it is read-only by being refused."""
+    return json_reply({"version": __version__, "repo": str(root),
+                       "readonly": request.param("_readonly") == "1"})
+
+
+def get_board(root: Path, request: Request) -> Reply:
+    return guarded(lambda: json_reply(board(root)))
+
+
+def get_fleet(root: Path, request: Request) -> Reply:
+    return guarded(lambda: json_reply(fleet(root)))
+
+
+def get_standup(root: Path, request: Request) -> Reply:
+    since = request.param("since", "24h")
+    return guarded(lambda: json_reply(standup(root, since=since)))
+
+
+def get_task(root: Path, request: Request) -> Reply:
+    task_id = request.param("id")
+    if not task_id:
+        return error_reply(400, "?id=<task> is required", "bad_request")
+    return guarded(lambda: json_reply(ask(root, task_id)))
+
+
+def get_activity(root: Path, request: Request) -> Reply:
+    """The history: the event log as a timeline, with a roll-up per actor.
+
+    One read for both, because they are one projection of one list — asking twice would mean two
+    scans of the same events, and a per-actor summary computed over a different window than the
+    timeline it sits next to would be a summary of something the reader cannot see.
+    """
+    since = request.param("since", HISTORY_WINDOW)
+    return guarded(lambda: json_reply(activity(root, since=since)))
+
+
+def get_search(root: Path, request: Request) -> Reply:
+    query = request.param("q")
+    if not query:
+        return json_reply([])
+    return guarded(lambda: json_reply(search(root, query)))
+
+
+def post_comment(root: Path, request: Request) -> Reply:
+    """A human talking to the agents. The mentions reach their inboxes like any other message.
+
+    The actor is RESOLVED, never taken from the request: a browser that could name its own
+    actor could post as somebody else's agent, and this thread is a permanent record.
+    """
+    payload = request.payload()
+    task_id, text = str(payload.get("task", "")), str(payload.get("text", "")).strip()
+    if not task_id or not text:
+        return error_reply(400, "`task` and `text` are required", "bad_request")
+    mentions = strings(payload, "mentions")
+    return guarded(lambda: json_reply(
+        update(root, task_id, comment=text, mentions=mentions)))
+
+
+def strings(payload: dict[str, Any], key: str) -> tuple[str, ...]:
+    """A tuple field off a JSON body. Tolerates the two shapes a client can produce — a list,
+    or one comma-separated field — because a message that silently reached nobody is the worst
+    way for this to fail, and the same is true of a label filter that silently matched
+    everything. Shared by `mentions` here and by `labels` on the agent endpoints."""
+    raw: object = payload.get(key)
+    if isinstance(raw, str):
+        return tuple(part.strip() for part in raw.split(",") if part.strip())
+    if isinstance(raw, list):
+        items = cast("list[object]", raw)
+        return tuple(str(item).strip() for item in items if str(item).strip())
+    return ()
+
+
+def post_status(root: Path, request: Request) -> Reply:
+    payload = request.payload()
+    task_id, status = str(payload.get("task", "")), str(payload.get("status", ""))
+    if not task_id or not status:
+        return error_reply(400, "`task` and `status` are required", "bad_request")
+    comment = str(payload.get("comment", ""))
+    return guarded(lambda: json_reply(
+        update(root, task_id, status=status, comment=comment)))
+
+
+def guarded(call: Callable[[], Reply]) -> Reply:
+    """Run an endpoint, turning a typed failure into its own HTTP status.
+
+    The taxonomy already carries `http_status`, so a new error type gets the right code the day
+    it is added rather than the day somebody remembers to map it here.
+    """
+    try:
+        return call()
+    except TaskopsError as err:
+        return error_reply(err.http_status, str(err), err.code)
+    except OSError as err:
+        return error_reply(500, str(err), "io_error")

taskops/transports/http/exchange.py

@@ -0,0 +1,80 @@
+"""The four replication endpoints — the wire half of remote sync.
+
+Its own module because these are the only endpoints whose caller is another taskops rather
+than the board: the shapes here are a CONTRACT a client codes against (`docs/exchange.md`),
+not something the UI and the server can rename together in one commit.
+
+Every write is a POST or a PUT, so `--readonly` refuses all four writes by METHOD in `policy`
+before any of this runs. A mirror on a screen cannot be pushed into.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+from ..._errors import ReportConflict
+from ...usecases import MAX_PAGE, accept_events, pull_events, read_report_file, write_report_file
+from ._wire import Reply, Request, error_reply, json_reply
+from .api import guarded
+
+__all__ = ["post_sync", "get_sync", "get_report_file", "put_report_file"]
+
+
+def post_sync(root: Path, request: Request) -> Reply:
+    """Relay a batch. `{"accepted": <how many were new>, "max_seq": <this server's cursor>}`."""
+    raw: object = request.payload().get("events")
+    if not isinstance(raw, list):
+        return error_reply(400, "`events` must be a list of events", "bad_request")
+    batch = cast("list[Any]", raw)
+    return guarded(lambda: json_reply(accept_events(root, batch)))
+
+
+def get_sync(root: Path, request: Request) -> Reply:
+    """One page after `?after=`, which is a cursor in THIS server's sequence and no other's."""
+    after = _int(request.param("after"), 0)
+    limit = _int(request.param("limit"), MAX_PAGE)
+    return guarded(lambda: json_reply(pull_events(root, after=after, limit=limit)))
+
+
+def get_report_file(root: Path, request: Request) -> Reply:
+    """The bytes this server holds for a label, verbatim — it never regenerates one to answer."""
+    label = request.param("label")
+    if not label:
+        return error_reply(400, "?label=<report> is required", "bad_request")
+
+    def run() -> Reply:
+        found = read_report_file(root, label)
+        if found is None:
+            return error_reply(404, f"no report {label} on this server", "no_such_report")
+        return json_reply(found)
+
+    return guarded(run)
+
+
+def put_report_file(root: Path, request: Request) -> Reply:
+    """Push a report. 409 unless it is strictly newer than what is here — see `usecases.reportfile`.
+
+    The conflict is answered by hand rather than through `guarded`, because `ours` and `theirs`
+    have to reach the client as NUMBERS. Its whole next move is deciding which copy survives,
+    and a sentence it would have to parse to find out is not an answer.
+    """
+    payload = request.payload()
+    label, content = str(payload.get("label", "")), str(payload.get("content", ""))
+    if not label or not content:
+        return error_reply(400, "`label` and `content` are required", "bad_request")
+    force = bool(payload.get("force"))
+
+    def run() -> Reply:
+        try:
+            return json_reply(write_report_file(root, label, content, force=force))
+        except ReportConflict as clash:
+            return json_reply({"error": str(clash), "code": clash.code,
+                               "ours": clash.ours, "theirs": clash.theirs}, 409)
+
+    return guarded(run)
+
+
+def _int(text: str, fallback: int) -> int:
+    """A query number, or the default. A cursor somebody typed by hand must not be a 500."""
+    return int(text) if text.lstrip("-").isdigit() else fallback