Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion docs/web-surface.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down Expand Up @@ -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` |
Expand Down
16 changes: 15 additions & 1 deletion src/system/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -479,6 +489,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
Expand Down
34 changes: 32 additions & 2 deletions src/system/intake.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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)
Expand All @@ -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,
Expand Down Expand Up @@ -145,14 +165,24 @@ 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"
)
# 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)
Expand Down
17 changes: 17 additions & 0 deletions src/system/tests/test_web_frontend.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading
Loading