sphinx-doc / sphinx-doc/sphinx
Linkcheck shouldn't retry on SSL errors
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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