X2: mokkari 4.8.0 + full-size candidate cover url

[ajslater]

comicbox 5.2.0, PR X2 of 2. Implements §6–§9 of
tasks/comicbox-5.2.0-plan.md. Independent of
#217 (X1), which mints the v5.2.0
NEWS section this appends to.

mokkari 4.8.0

4.8.0
shipped all three upstream asks from tasks/metron-rate-limit-plan.md,
now ticked there.

U1 (#167) — Session(rate_limiter=...)

comicbox's PacedSession subclass overrode the private
_execute_http_request and disabled _check_rate_limit. It collapses to
GateRateLimiter: a registration through the public hook. PacedSession
is deleted.

RateGate stays; mokkari's HeaderPacedRateLimiter is deliberately
not adopted, and the module docstring now carries the point-by-point
comparison so nobody simplifies it later. The short version: the
reference limiter does not wait at all before the first response (N
threads burst), blocks every caller on a 429 instead of releasing one
per freed slot, has no per_minute ceiling, no stats, and raises on the
daily window by comparing the server's epoch reset against the local
clock — the clock-drift trap the gate was designed around, and which
5.1.1's Skipped(reason="quota_reserved") abort semantics depend on not
hitting.

One private reach remains: Session._http, for a requests response
hook. The rate_limiter hook carries no URL, no status code and no raw
headers, and 5.1.2's telemetry — per-endpoint counts and "responses
without rate-limit headers, by status", reported to Metron's maintainer —
needs all three. The hook fires inside _http.request, which preserves
the old override's observe → cooldown → release order. Pacing no longer
depends on any private seam. A public accessor is filed as follow-up U7;
per the repo's convention I have not offered upstream a patch.

U2 (#168) — bounded pagination 429 retries

With a limiter set, a 429 mid-pagination retries the page through the
limiter without sleeping, so the wait is the gate's rebuilt window
rather than two stacked delays. No comicbox code compensated for the old
unbounded loop, so nothing was deleted. Two consequences are now tested:
the retry does not call mokkari.session.time.sleep, and a spent daily
quota (RateGate.acquire → OnlineLookupAbortedError, not a
RateLimitError) propagates out of a paginated call instead of being
swallowed — the 5.1.1 abort semantics now hold mid-pagination too.

U3 (#169) — pooled requests.Session

One TLS handshake per run instead of per request. Two consequences
handled: close_shared_sessions() releases the pool at the end of every
Runner.run() (read out of sys.modules, so an offline run still never
imports mokkari) and from the new OnlineSession.close() / context
manager; and an os.register_at_fork handler drops inherited sessions in
a child, rebinding the lock rather than taking it — the thread that held
it at fork time does not exist in the child.

CandidateSummary.cover_url_full

Display only. The matcher keeps hashing cover_url: hashing a larger
image moves every score and would need a fresh calibration run.

• ComicVine picks largest-first (original_url → medium_url) and
  never falls back to small_url or thumbnail — a record with only
  those tiers has nothing larger to show, and None is what a frontend
  keys "no hover" on.
• Metron serves one full-size image per issue, so both urls are the same,
  and both are None with no image.
• Zero API budget: the six ComicVine Images variants ride in the search
  response comicbox already paid for.

Accounting change

record_http_request loses its blocked_seconds parameter; the gate
wait comes in on the new record_gate_wait. _ApiCounts.requests now
counts responses received, which is what the server's own logs show;
a send that never answered appears only under connection_failures,
where it used to be double-counted under its endpoint too.

Test migration

Every test that patched mokkari.session.requests.request was
intercepting nothing under 4.8.0 — sends go through Session._http. They
now mount a requests.adapters.BaseAdapter (new
tests/util/metron_transport.py), which runs the whole real stack:
requests.Session.send, comicbox's response hook, mokkari's cookie
policy and the pool, exactly as production does.

Verification

make fix && make lint && make ty && make complexity

• make lint → 0 errors, 0 warnings, 0 notes
• make ty → All checks passed!
• make complexity → no functions over 15; radon cc --min C and
  mi --min B both silent

make test → exit=0
2208 passed, 1 skipped, 17 warnings in 44.71s

uv.lock resolves mokkari 4.8.0. CI reports skipping on PRs into
develop by design; the local sequence above is the verification.

Deliberate non-adoption

HeaderPacedRateLimiter (above); even spacing of sends (the gate's
sliding log is already exact to DRF's, and spacing would slow small
batches for nothing); Session.last_cache_status (diagnostic only,
unchanged from the 4.6.0 audit).

Public surface codex Wave 2 imports

CandidateSummary.cover_url_full, OnlineSession.close().

🤖 Generated with Claude Code