Skip to content

Fetch feeds through an optional HTTP or SOCKS proxy - #175

Merged
iantrich merged 3 commits into
masterfrom
proxy-support
Nov 15, 2026
Merged

iantrich merged 3 commits into
masterfrom
proxy-support

Conversation

@iantrich

Copy link
Copy Markdown
Member

Closes #27

Why

Some feeds are blocked on the user's network or in their country. Until now the only way to route feed requests through a proxy was the HTTP_PROXY / HTTPS_PROXY / ALL_PROXY environment variables, which are awkward to set on Home Assistant OS and apply to every feed at once.

What changed

  • New per-feed proxy option (setup form, options form and YAML). Supported schemes: http, https, socks4, socks4a, socks5, socks5h. Empty means no proxy, so existing feeds behave exactly as before, environment variables included.
  • fetch_feed passes the proxy to requests for both http and https feeds. file:// feeds ignore it.
  • The validation fetch during setup and reconfigure uses the proxy, so a feed that passes setup also works when the sensor polls.
  • Validation: a malformed proxy URL shows a new invalid_proxy error on its field in the UI, before anything is fetched. In YAML it is rejected by config validation.
  • Passwords: a password in user:pass@host is masked as *** in FeedReader.__repr__ and in the coordinator's "Unable to fetch" error.
  • New requirement: PySocks>=1.7.1 in manifest.json and pyproject.toml, needed for the socks* schemes.
  • Strings: the field label, help text and error message are in strings.json and the en/de/el translations.
  • README: a YAML example, a row in the reference table, and notes:
    • prefer socks5h so the proxy also resolves the host name, which matters when DNS is what blocks the site
    • entry images and links are opened by the browser, not through the proxy
    • the environment variables remain an alternative

Notes for reviewers

  • The proxy password is still stored in plain text in the config entry, like every other option. The README says so.
  • tests/test_proxy.py starts small local HTTP and SOCKS5 proxies on 127.0.0.1, using the socket_enabled fixture. Their threads are joined at teardown, so HA's lingering-thread check stays happy. The feed URL is http://blocked.invalid/rss, which can't resolve locally, so the tests only pass if the request really goes through the proxy. The SOCKS test also checks that socks5h sends the host name to the proxy rather than a resolved IP address.
  • test_validate_feed_url_sends_user_agent was updated for the extra proxy argument.
  • Tested with the full suite (219 passed), ruff and mypy. Not yet tried against a real proxy on a live HA install.

🤖 Generated with Claude Code

iantrich and others added 3 commits November 15, 2026 11:26
Feeds that are blocked on the user's network or in their country could not
be read at all: the only way to route requests through a proxy was the
HTTP(S)_PROXY environment variables, which are hard to set on Home
Assistant OS and apply to every feed.

Each feed now has an optional proxy URL (http, https, socks4, socks4a,
socks5 or socks5h; PySocks is added for the socks schemes). It is used for
the sensor's polls and for the validation fetch during setup and
reconfigure, and is available in the setup and options forms and in YAML.
Malformed URLs are rejected on their field (UI) or by config validation
(YAML). A password in the proxy URL is masked in the reader's repr and in
fetch error messages. file:// feeds ignore the proxy, and an empty value
keeps the previous behavior, environment variables included.

Closes #27

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The pre-commit ruff hook in CI reformats the old signature and then flags
ANN401 on **overrides.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
mypy in CI types server_address as str | bytes, so formatting the host
tripped str-bytes-safe. The test servers always bind to 127.0.0.1.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@iantrich
iantrich merged commit 09e39db into master Nov 15, 2026
6 checks passed
@iantrich
iantrich deleted the proxy-support branch November 15, 2026 17:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

add socks proxy support

1 participant