Bound docling-serve load from public readiness checks

[szweibel]

Problem

/health/ready is exempt from identity (_PUBLIC_IDENTITY_PATHS) and is exposed publicly at tools.ailab.gc.cuny.edu/pdf-accessibility/health/ready. On every call, _docling_check opened a new client and sent a bearer-authenticated GET {DOCLING_SERVE_URL}/health with up to 3 connect attempts. The number of outbound requests to docling-serve on the Tailscale host scaled directly with anonymous request volume.

Change

• The remote probe moves into _probe_docling_serve. _cached_docling_serve_probe shares a single probe task per (URL, token) for 30 seconds. Concurrent callers await the same in-flight task, and later callers in the window reuse its result. Failures are cached too, so an unreachable docling-serve isn't hit repeatedly. asyncio.shield stops one client disconnect from cancelling the shared probe.
• Outbound load is now at most one probe per 30 s per process, whatever the inbound traffic.
• The README documents the probe interval.

Why not move the probe off public readiness

• /health/ready has one consumer: the post-deploy curl -fsS in the README, run against both local and public URLs. The Docker HEALTHCHECK and CI smoke test use /health.
• The NML deploy uses the slim image, so it can't process PDFs without docling-serve. Dropping reachability from readiness would let that check pass on a deploy that can't do work.
• No orchestrator routes traffic by readiness, so a cold or slow docling-serve only affects the report, not whether jobs are accepted. Jobs still retry Docling on their own path.
• The app has no admin-authenticated diagnostics surface. Adding one would be new scope.

The response shape, the 200/503 semantics and the checks.docling.metadata.health_check values are unchanged.

Tests

• test_concurrent_readiness_requests_share_one_remote_docling_probe: 25 concurrent calls plus one sequential call result in 1 outbound request.
• test_remote_docling_probe_failure_is_cached_until_window_expires: a failure is reused until the window ends, then re-probed (clock is monkeypatched).
• An autouse fixture clears the cache between tests.
• ./scripts/check.sh passes: 535 backend tests, frontend lint and build.

🤖 Generated with Claude Code