sphinx-doc / sphinx-doc/sphinx

Linkcheck shouldn't retry on SSL errors

Open
#9,592 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

builder:linkcheck type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

When linkcheck sees SSLError it still retries the HTTP request hoping for different results. It shouldn't do this and it's actually a great place for optimization.

(guides/supporting-windows-using-appveyor: line  152) broken    http://tox.testrun.org - HTTPSConnectionPool(host='tox.testrun.org', port=443): Max retries exceeded with url: / (Caused by SSLError(SSLCertVerificationError("hostname 'tox.testrun.org' doesn't match 'codespeak.net'")))
How to Reproduce
$ git clone https://github.com/pypa/packaging.python.org
$ cd packaging.python.org
$ pip install nox virtualenv -U
$ nox -s linkcheck
# After this, see the error cited above
Expected behavior

Linkcheck should mark links as broken, the first time it sees TLS errors related to fetching the respective URLs.
Moreover, linkcheck should memorize hostnames that produced have broken TLS configuration and skip checking any further links having the same domain — they'll result in the same issue so it's reasonable to mark them all broken right away saving resources and making the check fail fast.

Your project

https://github.com/pypa/packaging.python.org

Screenshots

No response

OS

GHA CI / Ubuntu 20.04

Python version

CPython v3.9.6

Sphinx version

v4.0.3

Sphinx extensions

sphinx.ext.extlinks, sphinx.ext.intersphinx, sphinx.ext.todo, sphinx_inline_tabs, sphinx_copybutton

Extra tools

No response

Additional context

https://github.com/pypa/packaging.python.org/pull/968/checks#step:7:116

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by running nox -s linkcheck in the packaging.python.org reproduction described in the issue and inspect the linkcheck entry point and its request retry behavior. Verify the cited TLS hostname mismatch, then confirm that the first TLS error marks the URL broken, avoids retries, and prevents further checks for the same hostname.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.