From eb349f7565ac3229a114188f789f456573794752 Mon Sep 17 00:00:00 2001 From: Deep-Sixed <281237415+Deep-Sixed@users.noreply.github.com> Date: Sat, 26 Sep 2026 01:01:34 +0000 Subject: [PATCH 1/2] Let a refusal reach the browser, and a bad limit stay the caller's Two findings from the review of #36-#40, both in the intake code #36 added. A refusal decided on the envelope -- 413, 415, the namespace 400 -- is answered before a byte of the body is read, which is right, and then the socket was closed on whatever the client had sent, which is not. Closing on unread bytes is a reset, and a reset can overtake the response; on Windows it discards a response the client has not read yet. The page always sends the file it was given, so an operator choosing a 3 MB message could see "Failed to fetch" instead of the ceiling that refused it. The surface now settles every response the same way: write the answer, shut its own send side, then read and discard whatever the client is still sending, bounded at 16 MiB and five seconds, and only then close. Nothing about what is decided, or when, changes -- the answer is written before the drain begins and the drained bytes are never parsed, stored or kept. The socket is reached as `self.request`, socketserver's own name for it, because this package is mechanically forbidden the word `connection` and that guard is right to be. The suite could not see this. Every pre-read refusal was asserted with transmit=False, which proves the surface decides before reading and cannot prove what a browser sees, because a browser always sends the body. That was my choice in #39 and #40, and I did not say what it left untested. These tests send it: unfixed surface, deterministic orderly-close test FAIL 20/20 runs unfixed surface, over-ceiling full-body test FAIL 10/10, then 1 pass in 3 drain with no time bound FAIL (thread held) drain without shutting the send side first FAIL (no early end-of-stream) The small-body 415 and 400 full-body cases never fail on Linux; they are there for Windows, where the reset destroys the response rather than trailing it. `gmail-ingest --limit 0` reported "the mailbox could not be read". The service checked label_ids before its try and let limit fall inside it, where every failure becomes SourceUnreadable -- and only after the identity read had spent the credential. The limit is now checked where label_ids is, against the reader's own rule, and the CLI refuses a non-positive --limit before Gmail or the database is touched. service limit check removed FAIL (4 cases) CLI limit check removed FAIL Finding #1 of the review, a malformed read token stopping serve, is not in this change: whether that launch should refuse or start without Gmail is a decision still open. Gates: 1686 -> 1696 tests, ruff check and format clean, verify_tree 100/5/1, verify_secrets and verify_wheel PASS. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01B8kjhqYENShpeZ16QDnsyo --- src/system/cli.py | 4 + src/system/intake.py | 7 +- src/system/tests/test_web_intake.py | 178 ++++++++++++++++++++++++++++ src/system/web/server.py | 64 +++++++++- 4 files changed, 251 insertions(+), 2 deletions(-) diff --git a/src/system/cli.py b/src/system/cli.py index 29f7e8a..c4567fc 100644 --- a/src/system/cli.py +++ b/src/system/cli.py @@ -479,6 +479,10 @@ def main(): parser.error(f"gmail-ingest requires {TOKEN_VARIABLE} in the environment") if not args.mailbox or not args.skill: parser.error("gmail-ingest requires --mailbox and at least one --skill") + # Refused here, before the identity read below contacts Gmail: a bound that can never + # be satisfied is the operator's mistake, and it should not cost a credential to learn. + if args.limit < 1: + parser.error("gmail-ingest requires a positive --limit") reader = GmailReader(GmailCredentials(token, args.mailbox)) # reader.identifiers()/fetch()/messages() already refuse to run against an # unverified or mismatched mailbox identity on their own, and IntakeActions verifies diff --git a/src/system/intake.py b/src/system/intake.py index 81905b0..69e2fe6 100644 --- a/src/system/intake.py +++ b/src/system/intake.py @@ -151,8 +151,13 @@ def ingest_gmail(self, query: str = "", label_ids=(), limit: int = DEFAULT_GMAIL ) # Shaped before the try, so a caller's own bad argument stays a caller's error. Inside # it, everything becomes `SourceUnreadable`, which is a claim about the provider side - # that a TypeError raised here would not support. + # that a TypeError raised here would not support. The limit is checked here for the + # same reason and against the same rule the reader applies: left to the reader, a + # zero would be reported as a mailbox that could not be read, after the identity read + # had already spent the credential on a request that was never going to run. label_ids = tuple(label_ids) + if type(limit) is not int or limit < 1: + raise ValueError("A positive result limit is required") try: namespace = self.gmail_reader.verify_identity() messages = self.gmail_reader.messages(query=query, label_ids=label_ids, limit=limit) diff --git a/src/system/tests/test_web_intake.py b/src/system/tests/test_web_intake.py index 3f970f1..65c4480 100644 --- a/src/system/tests/test_web_intake.py +++ b/src/system/tests/test_web_intake.py @@ -1267,3 +1267,181 @@ def test_what_the_terminal_announces_matches_what_the_browser_is_offered(reposit offered = client.read("/api/v1/intake/sources")[1] announced = web.sources(inbound) assert announced == [name for name in ("eml", "gmail") if offered[name]["available"]] + + +# --- the request a browser actually makes ----------------------------------------------------- +# +# Every refusal above is asserted with `transmit=False`, which proves the surface decides before +# it reads. It cannot prove what the page sees, because the page always sends the body: `fetch` +# streams the file it was given whether or not anyone will read it. These send it. + + +def upload(surface, declared: int, *, media: str = web.RFC822) -> socket.socket: + """Open a command connection and send its envelope, declaring `declared` body bytes.""" + connection = socket.create_connection((web.LOOPBACK, surface.server_port), timeout=10) + connection.sendall( + ( + "POST /api/v1/intake/eml HTTP/1.1\r\n" + f"Host: {surface.authority}\r\n" + f"Origin: {surface.origin}\r\n" + f"{web.TOKEN_HEADER}: {surface.token}\r\n" + f"Content-Type: {media}\r\n" + f"{web.NAMESPACE_HEADER}: {NAMESPACE}\r\n" + f"Content-Length: {declared}\r\n" + "\r\n" + ).encode("ascii") + ) + return connection + + +def answer(connection: socket.socket) -> tuple[int, dict]: + """Read exactly one response -- headers, then the length they declare -- and no further.""" + received = b"" + while b"\r\n\r\n" not in received: + chunk = connection.recv(65536) + assert chunk, "the connection ended before a response arrived" + received += chunk + head, _, payload = received.partition(b"\r\n\r\n") + lines = head.decode("iso-8859-1").split("\r\n") + fields = dict(line.split(": ", 1) for line in lines[1:]) + length = int(fields["Content-Length"]) + while len(payload) < length: + chunk = connection.recv(65536) + assert chunk, "the connection ended inside the response" + payload += chunk + return int(lines[0].split(" ")[1]), json.loads(payload[:length]) + + +@pytest.mark.parametrize( + "settings, expected", + [ + ({"raw": b"x" * (MAX_MESSAGE_BYTES + 1)}, 413), + ({"raw": eml(), "content_type": "text/plain"}, 415), + ({"raw": eml(), "namespace": None}, 400), + ], + ids=["over the ceiling", "not a message", "no declared source"], +) +def test_a_refusal_reaches_a_client_that_sends_the_whole_body( + client, repository, settings, expected +): + """The page's request, and the reason it is refused -- not a network failure instead. + + Repeated because the defect this guards against was a race: a reset overtook the refusal + in a minority of attempts on Linux and can discard it outright on Windows. One green + attempt would not have distinguished the fixed surface from the unfixed one. + """ + before = stored(repository) + for _ in range(5): + status, body = client.eml(**settings) + assert status == expected, body + assert "error" in body + assert stored(repository) == before + + +def test_a_refusal_ends_the_connection_cleanly_while_the_upload_is_still_arriving(client): + """Deterministic, where the test above is statistical. + + Half the upload is sent, the refusal is read, and then the other half follows -- exactly + what a browser does, since it cannot know the answer was decided on the envelope. A + surface that closed on the unread half would reset: the second half would fail to send, + or the final read would raise ECONNRESET. The surface must instead end its answer at once, + take the rest in, discard it, and close in order. + """ + declared = MAX_MESSAGE_BYTES + 1 + first = declared // 2 + connection = upload(client.surface, declared) + try: + connection.sendall(b"x" * first) + status, body = answer(connection) + assert status == 413, body + assert str(MAX_MESSAGE_BYTES) in body["error"] + # The end of the answer arrives while half the upload is still unsent, well inside the + # drain's five seconds: the surface shut its own send side rather than holding it open + # until the client was done. A client reading to end-of-stream is not kept waiting. + connection.settimeout(1.0) + assert connection.recv(1) == b"", "the answer was not followed by an orderly end of it" + connection.settimeout(10) + connection.sendall(b"x" * (declared - first)) + connection.shutdown(socket.SHUT_WR) + assert connection.recv(1) == b"", "the connection did not end in an orderly close" + finally: + connection.close() + + +def test_the_drain_lets_go_of_a_client_that_never_sends_what_it_declared(client, monkeypatch): + """A declaration is not a promise the surface waits on forever. + + The client declares an oversized body, reads its refusal, and then neither sends nor + closes. The handler must still finish, inside the drain's time bound, rather than hold a + thread for as long as the client cares to keep the socket open. + """ + monkeypatch.setattr(web, "DRAIN_SECONDS", 0.3) + finished = threading.Event() + original = web.Handler.finish + + def finish(self): + finished.set() + return original(self) + + monkeypatch.setattr(web.Handler, "finish", finish) + connection = upload(client.surface, MAX_MESSAGE_BYTES + 1) + try: + status, _ = answer(connection) + assert status == 413 + assert finished.wait(timeout=5), "the handler was still waiting on a silent client" + finally: + connection.close() + + +# --- a Gmail bound that can never be met ------------------------------------------------------ + + +@pytest.mark.parametrize("limit", [0, -1, True, 1.0], ids=["zero", "negative", "bool", "float"]) +def test_a_limit_that_can_never_be_met_is_the_callers_error_and_contacts_nothing(repository, limit): + """Refused before the identity read, and as the caller's own mistake. + + Inside `ingest_gmail`'s try, every failure is declared `SourceUnreadable` -- a claim that + the provider side failed. A zero limit is not that, and reporting it as "the mailbox could + not be read" sent an operator to look at their credential for a typo in their command. + """ + mailbox = Mailbox({"aaaa1111": eml()}) + actions = service(repository, reader=reading(mailbox)) + before = stored(repository) + with pytest.raises(ValueError, match="positive result limit"): + actions.ingest_gmail(limit=limit) + assert mailbox.asked == [], "the mailbox was contacted for a request that could never run" + assert stored(repository) == before + + +def test_gmail_ingest_refuses_a_limit_before_gmail_or_the_database_is_touched( + tmp_path, monkeypatch, capsys +): + mailbox = Mailbox({"aaaa1111": eml()}) + monkeypatch.setenv("CAREERSIGNAL_GMAIL_TOKEN", "synthetic-read-token") + monkeypatch.setattr( + "system.cli.GmailReader", lambda credentials: GmailReader(credentials, mailbox) + ) + path = tmp_path / "never.db" + monkeypatch.setattr( + "sys.argv", + [ + "careersignal", + "gmail-ingest", + "--db", + str(path), + "--mailbox", + MAILBOX, + "--skill", + "python", + "--limit", + "0", + ], + ) + from system import cli + + with pytest.raises(SystemExit) as exited: + cli.main() + assert exited.value.code == 2 + assert "positive --limit" in capsys.readouterr().err + assert mailbox.asked == [] + assert not path.exists() diff --git a/src/system/web/server.py b/src/system/web/server.py index 066e3eb..55b74df 100644 --- a/src/system/web/server.py +++ b/src/system/web/server.py @@ -43,6 +43,8 @@ import json import os import secrets +import socket +import time from http import HTTPStatus from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer from importlib import resources @@ -136,6 +138,16 @@ # rather than restated: it is what `Message` itself enforces, and a second number here could # only ever disagree with the one that counts. RFC822 = "message/rfc822" +# What a refusal leaves behind. Every refusal above is decided on the envelope, before a byte +# of the body is read -- but a browser sends the body anyway, and closing a socket with bytes +# still unread in it is a reset rather than a clean shutdown. A reset can reach the client +# before the refusal does, so the operator who chose a 3 MB file would see "Failed to fetch" +# instead of the ceiling that refused it. So once the answer is written, whatever the client is +# still sending is read and thrown away, up to this many bytes and for at most this long, and +# only then is the socket closed. Both bounds exist so a request cannot hold a thread by +# declaring a length it never sends, or by sending one it never finishes. +DRAIN_LIMIT = 16 * 1024 * 1024 +DRAIN_SECONDS = 5.0 # Operator-declared provenance for a local file, carried as a header because the body is the # message itself and has no room for a field. It is a declaration and not evidence -- unlike a # Gmail namespace, which the reader proves against the credential before anything is admitted. @@ -501,6 +513,9 @@ class Handler(BaseHTTPRequestHandler): server_version = "CareerSignal" sys_version = "" + # How much of the declared body has been read. Only `_body()` and `_material()` read one, + # and a refusal made before either leaves this at zero -- which is what `_settle()` drains. + consumed = 0 def log_message(self, format, *args): """Write nothing. @@ -1008,6 +1023,7 @@ def _material(self, limit) -> bytes: if length > limit: raise Oversized(f"A message may not exceed {limit} bytes") raw = self.rfile.read(length) + self.consumed = len(raw) if len(raw) != length: raise ValueError("The request body was shorter than its declared length") return raw @@ -1025,8 +1041,10 @@ def _body(self) -> dict: length = int(declared) if length > MAX_BODY: raise Oversized(f"A command may not exceed {MAX_BODY} bytes") + raw = self.rfile.read(length) + self.consumed = len(raw) try: - return json.loads(self.rfile.read(length).decode("utf-8")) + return json.loads(raw.decode("utf-8")) except (UnicodeDecodeError, json.JSONDecodeError) as exc: raise ValueError(f"The request body is not valid JSON: {exc}") from exc @@ -1105,6 +1123,50 @@ def _send(self, status, media, payload, extra, *, body): self.end_headers() if body: self.wfile.write(payload) + self._settle() + + def _settle(self): + """Finish the answer, then read and discard whatever the client is still sending. + + Nothing here changes what was decided or when: the response is already written, and + these bytes are never parsed, stored or kept. What changes is how the connection ends. + Closing with unread bytes is a reset, and a reset can overtake the response -- on + Windows it discards a response the client has not read yet -- so a refusal made + without reading would reach the operator as a network failure instead of a reason. + + The send side is shut first, so the client sees the whole answer and an orderly end + of it while the rest of its upload is still arriving. The drain is bounded in bytes and + in time (`DRAIN_LIMIT`, `DRAIN_SECONDS`); past either, the socket closes regardless, + because no refusal is worth holding a thread for a client that will not stop. + """ + declared = self.headers.get("Content-Length", "") + if not (declared.isascii() and declared.isdigit()): + return + remaining = min(int(declared) - self.consumed, DRAIN_LIMIT) + if remaining <= 0: + return + deadline = time.monotonic() + DRAIN_SECONDS + # `self.request` is the client's socket, under the name socketserver gives it. The + # handler's other alias for it shares a name with a database handle, which this + # package is mechanically forbidden to reach, and a guard that reads names should not + # have to be taught that two things called the same are different. + client = self.request + try: + self.wfile.flush() + client.shutdown(socket.SHUT_WR) + while remaining > 0: + left = deadline - time.monotonic() + if left <= 0: + break + client.settimeout(left) + chunk = self.rfile.read1(min(remaining, 64 * 1024)) + if not chunk: + break + remaining -= len(chunk) + except OSError: + # A timeout, or a client already gone. Either way there is nothing left to wait + # for, and the answer was written before any of this began. + pass class Surface(ThreadingHTTPServer): From e790142007382efc406a0343470acf0545f2ec17 Mon Sep 17 00:00:00 2001 From: Deep-Sixed <281237415+Deep-Sixed@users.noreply.github.com> Date: Mon, 28 Sep 2026 09:19:07 +0000 Subject: [PATCH 2/2] Start serve with a malformed Gmail read token, and say why Gmail is off A read token that could not even be constructed (a stray newline, a space, a blank --mailbox) raised out of _intake_service, so `serve` stopped before binding and `ingest` of a local .eml, which needs no Gmail grant, failed the same way. Per the operator's decision, the launch now starts. The intake service carries the credential's own reason instead of a reader: /intake/sources reports gmail {"available": false, "error": "credential_malformed", "detail": ...}, serve prints an "Error (credential_malformed)" line at startup, the Inbox shows the reason where the Gmail control would be, and /intake/gmail answers 409 intake_unavailable naming it. EML intake and decisions are unaffected. The reason is the credential class's message, which never repeats the token. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01B8kjhqYENShpeZ16QDnsyo --- docs/web-surface.md | 10 +- src/system/cli.py | 12 ++- src/system/intake.py | 27 ++++- src/system/tests/test_web_frontend.py | 17 ++++ src/system/tests/test_web_intake.py | 137 +++++++++++++++++++++++++- src/system/web/server.py | 6 ++ src/system/web/static/screens.js | 30 ++++-- 7 files changed, 228 insertions(+), 11 deletions(-) diff --git a/docs/web-surface.md b/docs/web-surface.md index a1bbb34..5e3ab56 100644 --- a/docs/web-surface.md +++ b/docs/web-surface.md @@ -359,6 +359,14 @@ With no launch profile: {"eml": {"available": false}, "gmail": {"available": false}, "profile": null} ``` +With a read credential that was supplied but could not be constructed — a stray newline in `CAREERSIGNAL_GMAIL_TOKEN`, a blank `--mailbox` — the launch still starts, and says why Gmail is off: + +```json +{"available": false, "error": "credential_malformed", "detail": "Access token must be visible ASCII with no spaces or control characters; check for a stray newline. The supplied value is not repeated here."} +``` + +That is the `gmail` member only; `eml` and `profile` are unaffected. `serve` prints the same code and reason as an `Error (credential_malformed)` line at startup, and the Inbox shows it where the Gmail control would be. `detail` is the credential class's own message, which never repeats the value it refused. + `namespace` appears only where there is a reader to name one. No token, no token length, no fragment of a token and no credential scope detail appears here, and `gmail.available` means *configured for this launch* — not that Google has just been asked. ### `POST /api/v1/intake/eml` @@ -446,7 +454,7 @@ New material can legitimately change what a later action sees: a further source | malformed command, wrong field type, unknown field, bad `limit`, blank or missing namespace, unparseable MIME | `400` | | bad/missing launch token | `401` | | bad/missing `Origin` | `403` | -| no launch profile, or Gmail requested without a read credential | `409` `intake_unavailable` | +| no launch profile, or Gmail requested without a usable read credential | `409` `intake_unavailable` | | body larger than the ceiling | `413` | | the EML route sent anything but `message/rfc822` | `415` | | the mailbox could not be read | `502` `source_unreadable` | diff --git a/src/system/cli.py b/src/system/cli.py index c4567fc..d3dc7b3 100644 --- a/src/system/cli.py +++ b/src/system/cli.py @@ -168,7 +168,17 @@ def _intake_service(repository, args, reader=None): """ if not args.skill: return None - return IntakeActions(repository, _intake_profile(args), reader or _gmail_reader(args)) + if reader is not None: + return IntakeActions(repository, _intake_profile(args), reader) + # A read credential that cannot even be constructed does not stop the launch: local intake + # and every decision are unaffected, so refusing to start would withhold the safe half of + # the workflow over the half that needs Gmail. The credential's reason travels with the + # service instead, and the operator is told at startup and by the Gmail command itself. + try: + reader = _gmail_reader(args) + except ValueError as refused: + return IntakeActions(repository, _intake_profile(args), gmail_unusable=str(refused)) + return IntakeActions(repository, _intake_profile(args), reader) def _declared_identity(args, parser): diff --git a/src/system/intake.py b/src/system/intake.py index 69e2fe6..b69d6d9 100644 --- a/src/system/intake.py +++ b/src/system/intake.py @@ -33,6 +33,11 @@ # the one surface where a single button press could otherwise become a mailbox walk. DEFAULT_GMAIL_BATCH = 25 +# Why Gmail intake is off when a read credential was supplied and could not be used. Stable, +# so a page or a script can tell "never configured" from "configured wrongly" without +# parsing a sentence. +CREDENTIAL_MALFORMED = "credential_malformed" + class IntakeUnavailable(RuntimeError): """This launch was not configured with the authority the request needs. @@ -68,11 +73,23 @@ class IntakeActions: Local `.eml` intake needs no credential at all, so a launch can legitimately have one source and not the other -- and the compose credential that creates drafts is a different grant entirely, which this service never sees. + + `gmail_unusable` is the other half of that answer: a read credential was supplied at + launch and could not even be constructed -- a stray newline in the token, a blank + mailbox. The launch still starts, because local intake and every decision are + unaffected, but it carries the credential's own reason so the operator is told what is + wrong instead of seeing Gmail intake silently missing. The reason is the credential + class's message, which never repeats the value it refused. """ - def __init__(self, repository: Repository, profile: Profile, gmail_reader=None): + def __init__( + self, repository: Repository, profile: Profile, gmail_reader=None, gmail_unusable=None + ): + if gmail_reader is not None and gmail_unusable is not None: + raise ValueError("A launch either holds a Gmail reader or reports why it cannot") self.repository, self.profile = repository, profile self.gmail_reader = gmail_reader + self.gmail_unusable = gmail_unusable # The existing composition, unchanged. Everything this service does to a message it # does by handing it here. self._intake = Intake(repository, profile) @@ -92,6 +109,9 @@ def available(self) -> dict: gmail = {"available": self.gmail_reader is not None} if self.gmail_reader is not None: gmail["namespace"] = self.gmail_reader.namespace + elif self.gmail_unusable is not None: + gmail["error"] = CREDENTIAL_MALFORMED + gmail["detail"] = self.gmail_unusable return { "eml": {"available": True}, "gmail": gmail, @@ -145,6 +165,11 @@ def ingest_gmail(self, query: str = "", label_ids=(), limit: int = DEFAULT_GMAIL adapter raised. The caller therefore knows, without inspecting anything, that the provider side failed and that nothing local was written. """ + if self.gmail_unusable is not None: + raise IntakeUnavailable( + "the Gmail read credential supplied at launch is malformed, so no mailbox was " + f"contacted: {self.gmail_unusable}" + ) if self.gmail_reader is None: raise IntakeUnavailable( "this launch has no Gmail read credential, so no mailbox was contacted" diff --git a/src/system/tests/test_web_frontend.py b/src/system/tests/test_web_frontend.py index b9b5a15..f5d2201 100644 --- a/src/system/tests/test_web_frontend.py +++ b/src/system/tests/test_web_frontend.py @@ -762,6 +762,23 @@ def test_an_unavailable_gmail_source_is_explained_rather_than_offered(): assert "different grant" in absent +def test_a_malformed_gmail_credential_is_shown_as_an_error_rather_than_as_absence(): + """Configured wrongly is not the same fact as never configured, and the page says which.""" + screens = code(STATIC / "screens.js") + copy = region(screens, "const INTAKE_COPY = {", "\n};") + malformed = region(copy, "gmailMalformed:", "profileLabel:") + assert "CAREERSIGNAL_GMAIL_TOKEN" in malformed and "restart" in malformed + off = region(screens, "function gmailOff(", "\nexport function intakeSection(") + assert "gmail.detail" in off and "gmailMalformed" in off + # The branch itself, not only the names in it: without this the page can ignore the + # error and show "not configured", and every string above is still present. + assert "if (!gmail.error)" in off + assert "gmailAbsent" in off + assert "innerHTML" not in off + section = region(screens, "export function intakeSection(", "\nfunction filtered(") + assert "gmailOff(state.sources.gmail)" in section + + @pytest.mark.parametrize("command", ["importEml", "importGmail"]) def test_the_browser_re_reads_after_taking_material_in(command): """New evidence moves more than a decision does, so more is re-read. diff --git a/src/system/tests/test_web_intake.py b/src/system/tests/test_web_intake.py index 65c4480..5311dea 100644 --- a/src/system/tests/test_web_intake.py +++ b/src/system/tests/test_web_intake.py @@ -30,7 +30,7 @@ from data import store from data.repository import Repository from recruiting.models import Profile -from system.intake import IntakeActions +from system.intake import CREDENTIAL_MALFORMED, IntakeActions, IntakeUnavailable from system.web import server as web MAILBOX = "operator@example.com" @@ -1219,6 +1219,141 @@ def test_serve_with_a_read_token_and_a_mailbox_has_gmail_intake(monkeypatch, cap capsys.readouterr() +# --- a read credential that was supplied and cannot be used ------------------------------------- + +# Each of these fails at construction, before anything is contacted. None may stop a launch. +MALFORMED = [ + pytest.param("synthetic read token", MAILBOX, id="space-in-token"), + pytest.param("synthetic-read-token\n", MAILBOX, id="trailing-newline"), + pytest.param("synthetic-read-token", " ", id="blank-mailbox"), +] + + +def unusable(repository, reason="a synthetic reason") -> IntakeActions: + return IntakeActions(repository, Profile(SKILLS, ("remote",)), gmail_unusable=reason) + + +def launched(monkeypatch, tmp_path, command, token, mailbox, *extra): + """Run one command the way an operator would, with this read credential in the environment.""" + monkeypatch.setenv("CAREERSIGNAL_GMAIL_TOKEN", token) + monkeypatch.delenv(COMPOSE_TOKEN_VARIABLE, raising=False) + served = [] + monkeypatch.setattr("system.cli.serve", lambda repository, **kwargs: served.append(kwargs)) + monkeypatch.setattr( + "sys.argv", + ["careersignal", command, "--db", str(tmp_path / "db"), "--skill", "python"] + + ["--mailbox", mailbox, *extra], + ) + from system import cli + + cli.main() + return served + + +@pytest.mark.parametrize(("token", "mailbox"), MALFORMED) +def test_serve_starts_with_a_malformed_read_credential_and_says_why( + monkeypatch, capsys, tmp_path, token, mailbox +): + """The operator's decision: start, and report the credential as an error once running. + + Local intake and every decision are unaffected by a Gmail token, so refusing to start + would withhold all of them over the one source that needs it. What must not happen + instead is Gmail intake going quietly missing, which reads as "not configured" to an + operator who did configure it. + """ + served = launched(monkeypatch, tmp_path, "serve", token, mailbox) + with pytest.raises(ValueError) as construction: + GmailCredentials(token, mailbox) + inbound = served[0]["inbound"] + assert inbound.available() == { + "eml": {"available": True}, + "gmail": { + "available": False, + "error": CREDENTIAL_MALFORMED, + "detail": str(construction.value), + }, + "profile": {"skills": ["python"], "locations": ["remote"]}, + } + assert "synthetic" not in json.dumps(inbound.available()), "the token reached discovery" + with pytest.raises(IntakeUnavailable, match="malformed") as refused: + inbound.ingest_gmail() + assert "synthetic" not in str(refused.value) + # Drafting is a separate authority, and a bad read token takes nothing from it. + assert served[0]["actions"] is not None + capsys.readouterr() + + +def test_a_local_message_is_taken_in_whatever_the_read_credential_says( + monkeypatch, capsys, tmp_path +): + """`ingest` needs no Gmail grant, so a malformed one in the environment cannot stop it.""" + path = tmp_path / "alert.eml" + path.write_bytes(eml()) + launched( + monkeypatch, + tmp_path, + "ingest", + "synthetic read token", + MAILBOX, + "--message", + str(path), + "--namespace", + NAMESPACE, + ) + assert json.loads(capsys.readouterr().out)["reviews"] + + +def test_the_surface_reports_a_malformed_read_credential_and_keeps_everything_else( + launch, repository +): + """Discovery carries the code and reason; the Gmail command refuses with them; EML works.""" + client = launch(unusable(repository)) + status, sources = client.read("/api/v1/intake/sources") + assert status == 200 + assert sources["gmail"] == { + "available": False, + "error": CREDENTIAL_MALFORMED, + "detail": "a synthetic reason", + } + assert sources["eml"] == {"available": True} + before = stored(repository) + status, body = client.gmail() + assert status == 409, body + assert body["error"] == "intake_unavailable" + assert "malformed" in body["detail"] and "a synthetic reason" in body["detail"] + assert stored(repository) == before + assert client.eml(eml())[0] == 200 + + +def test_serve_names_a_malformed_read_credential_as_an_error_once_it_is_running( + repository, monkeypatch +): + """Said at startup, as an error, and only when there is one to say.""" + monkeypatch.setattr( + web.Surface, "serve_forever", lambda self: (_ for _ in ()).throw(KeyboardInterrupt) + ) + said = [] + web.serve(repository, port=0, inbound=unusable(repository), announce=said.append) + assert [line for line in said if line.startswith("Error")] == [ + f"Error ({CREDENTIAL_MALFORMED}): Gmail intake is off. a synthetic reason" + ] + assert [line for line in said if line.startswith("Open ")], "the launch did not start" + # Not configuring Gmail is a choice rather than a mistake, and is not reported as one. + said.clear() + web.serve(repository, port=0, inbound=service(repository), announce=said.append) + assert not [line for line in said if line.startswith("Error")] + + +def test_a_service_cannot_hold_a_reader_and_report_it_unusable(repository): + with pytest.raises(ValueError, match="either"): + IntakeActions( + repository, + Profile(SKILLS, ("remote",)), + reading(Mailbox({})), + gmail_unusable="a synthetic reason", + ) + + def test_a_compose_credential_alone_gives_no_intake_authority(monkeypatch, capsys, tmp_path): """The independence stated as behaviour: one grant is not the other.""" monkeypatch.delenv("CAREERSIGNAL_GMAIL_TOKEN", raising=False) diff --git a/src/system/web/server.py b/src/system/web/server.py index 55b74df..d882850 100644 --- a/src/system/web/server.py +++ b/src/system/web/server.py @@ -1284,6 +1284,12 @@ def serve( if inbound else "This launch takes nothing in; intake needs at least one --skill" ) + # A credential that was supplied and could not be used is an error the operator made, not + # an absence they chose, so it is named here rather than left for a missing button to + # imply. The launch continues: nothing else depends on it. + unusable = inbound.available()["gmail"] if inbound else {} + if "error" in unusable: + announce(f"Error ({unusable['error']}): Gmail intake is off. {unusable['detail']}") announce(f"Open {surface.launch_url}") announce("This address is valid for this process only. Stop with Ctrl-C.") with surface: diff --git a/src/system/web/static/screens.js b/src/system/web/static/screens.js index 43668b0..d26acd6 100644 --- a/src/system/web/static/screens.js +++ b/src/system/web/static/screens.js @@ -886,6 +886,9 @@ const INTAKE_COPY = { "Gmail intake is not configured for this launch. It needs a read credential in " + "CAREERSIGNAL_GMAIL_TOKEN and a --mailbox; the compose credential that creates drafts is " + "a different grant and does not enable it.", + gmailMalformed: + "Gmail intake is off: the read credential supplied at launch is malformed. Fix " + + "CAREERSIGNAL_GMAIL_TOKEN or --mailbox and restart CareerSignal.", profileLabel: "Scored against", profileNote: "Launch configuration. It cannot be changed from this page, and no message can change it.", @@ -1013,6 +1016,25 @@ function intakeReport(report) { return block; } +function gmailOff(gmail) { + /* Never configured and configured wrongly are different facts, and only the second is an + * error. The detail is the credential's own reason, which never repeats the token, and it + * is placed as text like every other value on this page. + */ + const holder = put( + el("div", "intake-source"), + el("h4", "intake-source-title", INTAKE_COPY.gmailTitle), + ); + if (!gmail.error) { + return put(holder, el("p", "intake-note", INTAKE_COPY.gmailAbsent)); + } + return put( + holder, + el("p", "intake-note", INTAKE_COPY.gmailMalformed), + el("p", "intake-note", `${gmail.error}: ${gmail.detail}`), + ); +} + export function intakeSection(state, actions) { /* Offered only where it can operate. * @@ -1041,13 +1063,7 @@ export function intakeSection(state, actions) { ); put( holder, - state.sources.gmail.available - ? gmailControls(state, actions) - : put( - el("div", "intake-source"), - el("h4", "intake-source-title", INTAKE_COPY.gmailTitle), - el("p", "intake-note", INTAKE_COPY.gmailAbsent), - ), + state.sources.gmail.available ? gmailControls(state, actions) : gmailOff(state.sources.gmail), ); if (state.intake) { put(holder, intakeReport(state.intake));