Files
rss-to-opds/tests/test_config.py
2026-11-15 18:15:03 -05:00

488 lines
20 KiB
Python

"""Tests for configuration loading, interpolation and validation."""
from __future__ import annotations
import json
import os
import tempfile
import unittest
from pathlib import Path
from app.config import (
DEFAULT_BIND_HOST,
ConfigError,
describe_config,
load_config,
normalise_api_base,
password_digest,
resolve_config_path,
)
# Fixture credentials. These are throwaway values that exercise the schema; no
# real account is involved and neither value is a secret. They are applied
# through the helpers below so every test states its intent in one line.
FIXTURE_UPSTREAM_VALUE = "upstream-fixture-value"
FIXTURE_READER_VALUE = "reader-fixture-value"
REPO_ROOT = Path(__file__).resolve().parent.parent
EXAMPLE_CONFIG = REPO_ROOT / "config.example.json"
def with_upstream_credential(document: dict, value: str) -> dict:
"""Set the upstream FreshRSS API credential under test."""
document["freshrss"]["api_password"] = value
return document
def with_reader_credential(document: dict, value: str, username: str = "reader") -> dict:
"""Replace auth.users with one user carrying a clear-text credential."""
document["auth"]["users"] = [{"username": username, "password": value}]
return document
def with_reader_digest(document: dict, digest: str, username: str = "reader") -> dict:
"""Replace auth.users with one user carrying a pre-computed digest."""
document["auth"]["users"] = [{"username": username, "password_sha256": digest}]
return document
def with_conflicting_credentials(document: dict, value: str) -> dict:
"""A deliberately over-specified user, to exercise the conflict rule."""
document["auth"]["users"] = [
{
"username": "reader",
"password": value,
"password_sha256": password_digest(value),
}
]
return document
def base_config() -> dict:
"""A minimal valid configuration, ready to be mutated by a test."""
document = {
"server": {"port": 8080},
"freshrss": {
"url": "https://rss.example.com",
"username": "tyler",
"api_password": FIXTURE_UPSTREAM_VALUE,
},
"auth": {"users": [{"username": "tyler", "password": FIXTURE_READER_VALUE}]},
}
return document
class ConfigTestCase(unittest.TestCase):
"""Writes a config document into a temporary directory and loads it."""
def setUp(self):
self._dir = tempfile.TemporaryDirectory()
self.addCleanup(self._dir.cleanup)
self.dir = Path(self._dir.name)
def write(self, document, name: str = "config.json") -> str:
path = self.dir / name
if isinstance(document, str):
path.write_text(document, encoding="utf-8")
else:
path.write_text(json.dumps(document), encoding="utf-8")
return str(path)
def load(self, document, name: str = "config.json"):
return load_config(self.write(document, name))
def expect_problem(self, document, fragment: str) -> ConfigError:
"""Assert the config is rejected, and return the error for more checks."""
with self.assertRaises(ConfigError) as caught:
self.load(document)
joined = "\n".join(caught.exception.problems)
self.assertIn(fragment, joined)
return caught.exception
class LoadingTests(ConfigTestCase):
def test_minimal_config_uses_documented_defaults(self):
config = self.load(base_config())
self.assertEqual(config.server.host, DEFAULT_BIND_HOST)
self.assertEqual(config.server.port, 8080)
self.assertEqual(config.freshrss.items_per_page, 30)
self.assertTrue(config.freshrss.mark_read)
self.assertTrue(config.epub.include_images)
self.assertEqual(config.auth.users[0].username, "tyler")
self.assertEqual(len(config.auth.users[0].password_sha256), 64)
def test_default_bind_address_is_loopback(self):
# The wildcard belongs in the deployment's config file, not in the code:
# a stray `docker run -p 8080:8080` should not silently be reachable.
self.assertEqual(DEFAULT_BIND_HOST, "127.0.0.1")
def test_missing_file_is_a_clear_error(self):
with self.assertRaises(ConfigError) as caught:
load_config(str(self.dir / "nope.json"))
joined = "\n".join(caught.exception.problems)
self.assertIn("not found", joined)
self.assertIn("CONFIG_PATH", joined)
def test_invalid_json_reports_position(self):
error = self.expect_problem('{"server": {,}', "not valid JSON")
self.assertIn("line 1", "\n".join(error.problems))
def test_non_object_root_is_rejected(self):
self.expect_problem("[1, 2, 3]", "top level")
def test_source_path_is_recorded(self):
path = self.write(base_config())
self.assertEqual(load_config(path).source_path, str(Path(path).resolve()))
def test_resolve_config_path_prefers_explicit_then_env(self):
explicit = self.write(base_config(), "explicit.json")
self.assertEqual(resolve_config_path(explicit), explicit)
from_env = str(self.dir / "from-env.json")
os.environ["CONFIG_PATH"] = from_env
self.addCleanup(os.environ.pop, "CONFIG_PATH", None)
self.assertEqual(resolve_config_path(), from_env)
class ExampleConfigTests(unittest.TestCase):
"""The shipped example must load: a broken example is a broken first run.
This is also where the container's wildcard bind address is asserted. That
literal belongs in the deployment's configuration file, not in Python, and the
test proves the file really does override the loopback default.
"""
def setUp(self):
# The example deliberately leaves secrets to the environment.
os.environ["FRESHRSS_API_PASSWORD"] = FIXTURE_UPSTREAM_VALUE
os.environ["OPDS_PASSWORD_SHA256"] = password_digest(FIXTURE_READER_VALUE)
self.addCleanup(os.environ.pop, "FRESHRSS_API_PASSWORD", None)
self.addCleanup(os.environ.pop, "OPDS_PASSWORD_SHA256", None)
self.document = json.loads(EXAMPLE_CONFIG.read_text(encoding="utf-8"))
def test_example_config_exists_and_is_valid(self):
config = load_config(str(EXAMPLE_CONFIG))
self.assertEqual(config.warnings, [])
self.assertEqual(len(config.auth.users), 1)
def test_example_config_overrides_the_loopback_default(self):
config = load_config(str(EXAMPLE_CONFIG))
self.assertNotEqual(config.server.host, DEFAULT_BIND_HOST)
self.assertEqual(config.server.host, self.document["server"]["host"])
def test_example_keeps_secrets_out_of_the_file(self):
self.assertTrue(self.document["freshrss"]["api_password"].startswith("${"))
self.assertTrue(self.document["auth"]["users"][0]["password_sha256"].startswith("${"))
def test_example_is_self_documenting(self):
comments = [key for key in self.document if key.startswith("_")]
self.assertTrue(comments)
self.assertTrue(self.document["server"].get("_host"))
def test_example_interpolates_its_credentials(self):
self.assertEqual(
load_config(str(EXAMPLE_CONFIG)).freshrss.api_password, FIXTURE_UPSTREAM_VALUE
)
class InterpolationTests(ConfigTestCase):
def test_environment_variable_is_expanded(self):
os.environ["TEST_FRESHRSS_CREDENTIAL"] = "from-env"
self.addCleanup(os.environ.pop, "TEST_FRESHRSS_CREDENTIAL", None)
document = with_upstream_credential(base_config(), "${TEST_FRESHRSS_CREDENTIAL}")
self.assertEqual(self.load(document).freshrss.api_password, "from-env")
def test_environment_variable_default_is_used_when_unset(self):
os.environ.pop("TEST_UNSET_VAR", None)
document = with_upstream_credential(base_config(), "${TEST_UNSET_VAR:-fallback}")
self.assertEqual(self.load(document).freshrss.api_password, "fallback")
def test_missing_environment_variable_names_itself(self):
os.environ.pop("TEST_DEFINITELY_UNSET", None)
document = with_upstream_credential(base_config(), "${TEST_DEFINITELY_UNSET}")
error = self.expect_problem(document, "TEST_DEFINITELY_UNSET")
self.assertIn("freshrss.api_password", "\n".join(error.problems))
def test_secret_file_is_read_and_trimmed(self):
(self.dir / "upstream-secret").write_text("file-secret\n", encoding="utf-8")
# A relative path resolves against the config file's own directory.
document = with_upstream_credential(base_config(), "${file:upstream-secret}")
self.assertEqual(self.load(document).freshrss.api_password, "file-secret")
def test_secret_file_may_be_absolute(self):
absolute = self.dir / "absolute-secret"
absolute.write_text("abs", encoding="utf-8")
document = with_upstream_credential(base_config(), f"${{file:{absolute}}}")
self.assertEqual(self.load(document).freshrss.api_password, "abs")
def test_missing_secret_file_is_an_error(self):
document = with_upstream_credential(base_config(), "${file:not-there}")
self.expect_problem(document, "cannot read secret file")
def test_escaped_dollar_is_literal(self):
document = with_upstream_credential(base_config(), "$${NOT_A_REFERENCE}")
self.assertEqual(self.load(document).freshrss.api_password, "${NOT_A_REFERENCE}")
def test_interpolation_reaches_nested_arrays(self):
os.environ.pop("TEST_PW", None)
document = with_reader_credential(base_config(), "${TEST_PW:-pw}")
self.assertEqual(self.load(document).auth.users[0].password_sha256, password_digest("pw"))
def test_empty_reference_is_an_error(self):
document = with_upstream_credential(base_config(), "${}")
self.expect_problem(document, "empty ${}")
class FreshRSSTests(ConfigTestCase):
def test_api_base_appends_the_greader_suffix(self):
self.assertEqual(
normalise_api_base("https://rss.example.com"),
"https://rss.example.com/api/greader.php",
)
def test_api_base_keeps_an_existing_suffix(self):
self.assertEqual(
normalise_api_base("https://rss.example.com/api/greader.php"),
"https://rss.example.com/api/greader.php",
)
def test_api_base_preserves_a_path_prefix(self):
self.assertEqual(
normalise_api_base("https://example.com/freshrss/"),
"https://example.com/freshrss/api/greader.php",
)
def test_api_base_is_case_insensitive_about_the_suffix(self):
self.assertEqual(
normalise_api_base("https://e.com/API/GReader.php"),
"https://e.com/API/GReader.php",
)
def test_url_without_scheme_is_rejected(self):
document = base_config()
document["freshrss"]["url"] = "rss.example.com"
self.expect_problem(document, "must start with http:// or https://")
def test_required_fields_are_reported_together(self):
document = {"server": {}, "auth": {"users": [{"username": "u", "password": "p"}]}}
with self.assertRaises(ConfigError) as caught:
self.load(document)
joined = "\n".join(caught.exception.problems)
for fragment in ("freshrss.url", "freshrss.username", "freshrss.api_password"):
self.assertIn(fragment, joined)
def test_items_per_page_must_fit_the_request_ceiling(self):
document = base_config()
document["freshrss"]["items_per_page"] = 100
document["freshrss"]["max_items_per_request"] = 50
self.expect_problem(document, "must be at least")
def test_retries_and_timeouts_are_validated(self):
document = base_config()
document["freshrss"]["timeout_seconds"] = 0
document["freshrss"]["retries"] = -1
with self.assertRaises(ConfigError) as caught:
self.load(document)
joined = "\n".join(caught.exception.problems)
self.assertIn("timeout_seconds", joined)
self.assertIn("retries", joined)
def test_mark_read_can_be_disabled(self):
document = base_config()
document["freshrss"]["mark_read"] = False
self.assertFalse(self.load(document).freshrss.mark_read)
class TypeValidationTests(ConfigTestCase):
def test_port_must_be_a_number_in_range(self):
for value, fragment in (
("8080", "whole number"),
(-1, "at least"),
(70000, "at most"),
):
document = base_config()
document["server"]["port"] = value
self.expect_problem(document, fragment)
def test_port_zero_asks_the_operating_system_for_a_free_port(self):
# Useful for a local run or a test; a normal deployment sets a real port.
document = base_config()
document["server"]["port"] = 0
self.assertEqual(self.load(document).server.port, 0)
def test_boolean_field_rejects_a_number(self):
document = base_config()
document["freshrss"]["mark_read"] = 1
self.expect_problem(document, "must be true or false")
def test_integer_field_rejects_a_boolean(self):
# bool is an int subclass in Python; `true` must not become 1.
document = base_config()
document["server"]["port"] = True
self.expect_problem(document, "whole number")
def test_string_field_rejects_a_list(self):
document = base_config()
document["catalog"] = {"title": ["not", "a", "string"]}
self.expect_problem(document, "catalog.title: must be a string")
def test_string_list_rejects_scalars(self):
document = base_config()
document["catalog"] = {"exclude_feeds": "one-feed"}
self.expect_problem(document, "must be an array of strings")
def test_section_must_be_an_object(self):
document = base_config()
document["cache"] = "nope"
self.expect_problem(document, "cache: must be a JSON object")
def test_log_level_is_restricted(self):
document = base_config()
document["server"]["log_level"] = "chatty"
self.expect_problem(document, "must be one of")
def test_ttl_must_be_positive(self):
document = base_config()
document["cache"] = {"stream_ttl_seconds": 0}
self.expect_problem(document, "greater than 0")
class AuthTests(ConfigTestCase):
def test_users_are_required(self):
document = base_config()
del document["auth"]
error = self.expect_problem(document, "auth.users: required")
self.assertIn("credentials", "\n".join(error.problems))
def test_empty_user_list_is_rejected(self):
document = base_config()
document["auth"]["users"] = []
self.expect_problem(document, "at least one user")
def test_clear_text_password_is_hashed(self):
document = with_reader_credential(base_config(), FIXTURE_READER_VALUE)
config = self.load(document)
self.assertEqual(
config.auth.users[0].password_sha256, password_digest(FIXTURE_READER_VALUE)
)
def test_clear_text_password_is_never_kept_in_the_config_object(self):
document = with_reader_credential(base_config(), FIXTURE_READER_VALUE)
config = self.load(document)
self.assertNotIn(FIXTURE_READER_VALUE, json.dumps(config.auth.users[0].__dict__))
def test_sha256_password_is_accepted_and_lowercased(self):
document = with_reader_digest(base_config(), password_digest("s3cret").upper())
self.assertEqual(
self.load(document).auth.users[0].password_sha256, password_digest("s3cret")
)
def test_both_password_forms_is_an_error(self):
document = with_conflicting_credentials(base_config(), FIXTURE_READER_VALUE)
self.expect_problem(document, "not both")
def test_neither_password_form_is_an_error(self):
document = base_config()
document["auth"]["users"] = [{"username": "a"}]
self.expect_problem(document, "needs password or password_sha256")
def test_malformed_digest_is_rejected(self):
document = with_reader_digest(base_config(), "deadbeef")
self.expect_problem(document, "64 hex characters")
def test_duplicate_usernames_are_rejected(self):
document = base_config()
document["auth"]["users"] = [
{"username": "a", "password": FIXTURE_READER_VALUE},
{"username": "a", "password": FIXTURE_UPSTREAM_VALUE},
]
self.expect_problem(document, "duplicate username")
def test_user_must_be_an_object(self):
document = base_config()
document["auth"]["users"] = ["tyler"]
self.expect_problem(document, "must be a JSON object")
def test_realm_is_configurable(self):
document = base_config()
document["auth"]["realm"] = "Reading"
self.assertEqual(self.load(document).auth.realm, "Reading")
class TlsTests(ConfigTestCase):
def test_cert_without_key_is_rejected(self):
document = base_config()
document["server"]["tls"] = {"cert_file": str(self.dir / "cert.pem")}
self.expect_problem(document, "must be set together")
def test_missing_certificate_file_is_rejected(self):
document = base_config()
document["server"]["tls"] = {
"cert_file": str(self.dir / "absent-cert.pem"),
"key_file": str(self.dir / "absent-key.pem"),
}
self.expect_problem(document, "no such file")
def test_present_certificate_pair_is_accepted(self):
cert = self.dir / "cert.pem"
key = self.dir / "key.pem"
cert.write_text("dummy", encoding="utf-8")
key.write_text("dummy", encoding="utf-8")
document = base_config()
document["server"]["tls"] = {"cert_file": str(cert), "key_file": str(key)}
config = self.load(document)
self.assertEqual(config.server.tls_cert_file, str(cert))
class WarningTests(ConfigTestCase):
def test_unknown_key_is_reported_with_a_suggestion(self):
document = base_config()
document["freshrss"]["mark-read"] = True
config = self.load(document)
self.assertTrue(config.warnings)
self.assertIn("freshrss.mark-read", config.warnings[0])
self.assertIn("mark_read", config.warnings[0])
def test_unknown_user_key_is_reported(self):
document = base_config()
document["auth"]["users"] = [
{"username": "a", "password": FIXTURE_READER_VALUE, "passwrod": "typo"}
]
config = self.load(document)
self.assertIn("auth.users[0].passwrod", config.warnings[0])
def test_unknown_tls_key_is_reported(self):
document = base_config()
document["server"]["tls"] = {"certfile": "/x", "keyfile": "/y"}
config = self.load(document)
self.assertEqual(len(config.warnings), 2)
def test_unknown_section_is_reported(self):
document = base_config()
document["cach"] = {"max_entries": 10}
config = self.load(document)
self.assertIn("cach:", config.warnings[0])
self.assertIn("cache", config.warnings[0])
def test_warnings_do_not_block_a_valid_config(self):
document = base_config()
document["nonsense"] = 1
self.assertEqual(len(self.load(document).warnings), 1)
class DescribeConfigTests(ConfigTestCase):
def test_password_is_redacted_in_the_summary(self):
summary = describe_config(self.load(base_config()))
self.assertNotIn(FIXTURE_UPSTREAM_VALUE, summary)
self.assertIn("rss.example.com/api/greader.php", summary)
def test_summary_lists_users(self):
self.assertIn("tyler", describe_config(self.load(base_config())))
def test_summary_notes_tls_state(self):
summary = describe_config(self.load(base_config()))
self.assertIn("127.0.0.1:8080", summary)
if __name__ == "__main__":
unittest.main()