Initial commit

This commit is contained in:
2026-11-15 18:15:03 -05:00
commit b76aea2899
36 changed files with 9424 additions and 0 deletions

841
app/config.py Normal file
View File

@@ -0,0 +1,841 @@
"""JSON configuration: loading, interpolation, validation.
Configuration is a single JSON document, which keeps deployment to "mount a file
and run the container". Two things make that practical for a service holding
credentials:
*Interpolation.* Any string value may contain ``${VAR}`` (an environment
variable, optionally with a ``:-default``), ``${file:/run/secrets/x}`` (a file,
which is how Docker secrets arrive), or ``$${`` for a literal ``${``. Secrets
therefore never have to be written into the JSON document that gets committed.
*Aggregated validation.* Every problem found is reported in one pass with the
JSON path that caused it, because a container that exits on the first of five
typos is a slow way to configure a service. Unknown keys are reported too, as
warnings: a misspelled ``mark_read`` that silently defaulted to something else is
exactly the kind of thing that costs an hour.
*Comments.* JSON has no comment syntax, so any key beginning with an underscore
is treated as one: it is ignored, never interpolated, and never reported as
unknown. That lets ``config.example.json`` explain itself.
"""
from __future__ import annotations
import hashlib
import json
import logging
import os
import re
from collections.abc import Iterator
from contextlib import contextmanager
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
LOGGER = logging.getLogger(__name__)
CONFIG_PATH_ENV = "CONFIG_PATH"
# Default listen address. Loopback is the safe default for a service that holds
# a whole reading queue: running it directly on a host binds only to that host.
# A container is the one case that needs the wildcard, because the published port
# only reaches the process through the container's own interface -- so the
# shipped config.example.json and docker-compose.yaml set it explicitly, and there
# is exactly one place (the mounted configuration) that decides exposure.
DEFAULT_BIND_HOST = "127.0.0.1"
_DEFAULT_PATHS = ("/config/config.json", "config.json")
_INTERPOLATION_RE = re.compile(r"\$\{([^{}]*)\}")
_SHA256_RE = re.compile(r"\A[0-9a-fA-F]{64}\Z")
_ESCAPED_DOLLAR = "\x00escaped-dollar\x00"
GREADER_SUFFIX = "/api/greader.php"
_LOG_LEVELS = frozenset({"debug", "info", "warning", "error", "critical"})
class ConfigError(Exception):
"""Raised when the configuration cannot be used.
Carries every problem found, so a human sees the whole list at once.
"""
def __init__(self, problems: list[str], source: str = "") -> None:
self.problems = problems
self.source = source
where = f" in {source}" if source else ""
detail = "\n".join(f" - {problem}" for problem in problems)
super().__init__(f"invalid configuration{where}:\n{detail}")
@dataclass
class ServerConfig:
"""HTTP listener settings."""
host: str = DEFAULT_BIND_HOST
port: int = 8080
log_level: str = "info"
# Absolute base URL for links. When unset, links are built from the request
# Host header, which is fine behind a proxy but lets a spoofed Host shape the
# catalog URLs -- so a public deployment should set this.
public_base_url: str | None = None
# Honour X-Forwarded-Proto/Host/Prefix. Only enable behind a proxy you trust,
# because the headers are client-controlled otherwise.
trust_proxy_headers: bool = False
# Optional Host allowlist; a request with any other Host is refused.
allowed_hosts: list[str] = field(default_factory=list)
tls_cert_file: str | None = None
tls_key_file: str | None = None
@dataclass
class FreshRSSConfig:
"""Upstream FreshRSS connection."""
api_base: str
username: str
api_password: str
verify_tls: bool = True
ca_file: str | None = None
timeout_seconds: float = 15.0
retries: int = 2
# Mark the article read upstream once its EPUB has been delivered.
mark_read: bool = True
items_per_page: int = 30
max_items_per_request: int = 200
# How far back the Read section looks. Read items are filtered client-side
# (only the unread filter is a documented upstream parameter), so this bounds
# the history that section can show.
read_window_items: int = 200
# Article body cap before parsing; prevents one enormous feed item from
# dominating memory.
max_content_bytes: int = 1_048_576
@dataclass
class CatalogConfig:
"""OPDS catalog presentation."""
title: str = "FreshRSS OPDS"
author: str = "FreshRSS"
language: str = "en"
publisher: str | None = None
show_unread_counts: bool = True
show_read_section: bool = True
show_starred: bool = True
hide_empty_categories: bool = False
exclude_categories: list[str] = field(default_factory=list)
exclude_feeds: list[str] = field(default_factory=list)
@dataclass
class EpubConfig:
"""EPUB generation."""
include_images: bool = True
allowed_image_hosts: list[str] = field(default_factory=list)
blocked_image_hosts: list[str] = field(default_factory=list)
max_images_per_article: int = 20
max_image_bytes: int = 2_097_152
max_total_image_bytes: int = 16_777_216
image_timeout_seconds: float = 10.0
cover_image: bool = True
include_source_link: bool = True
stylesheet: str | None = None
max_epub_bytes: int = 33_554_432
@dataclass
class AuthUser:
"""One Basic-auth principal. Passwords are always compared as digests."""
username: str
password_sha256: str
@dataclass
class AuthConfig:
"""HTTP Basic credentials.
Authentication is mandatory by design: this catalog exposes the whole of a
reading queue, and an unauthenticated OPDS endpoint on a routable address is
an open book. Basic auth must therefore sit behind TLS (a reverse proxy, or
the TLS options under ``server``), because the header is not encrypted.
"""
realm: str = "OPDS"
users: list[AuthUser] = field(default_factory=list)
max_failures_per_minute: int = 10
throttle_seconds: float = 60.0
@dataclass
class CacheConfig:
"""In-memory cache lifetimes. Nothing is ever written to disk."""
subscriptions_ttl_seconds: float = 300.0
stream_ttl_seconds: float = 60.0
item_ttl_seconds: float = 900.0
max_entries: int = 512
@dataclass
class Config:
"""The fully resolved configuration."""
server: ServerConfig
freshrss: FreshRSSConfig
catalog: CatalogConfig
epub: EpubConfig
auth: AuthConfig
cache: CacheConfig
source_path: str = ""
warnings: list[str] = field(default_factory=list)
def resolve_config_path(explicit: str | None = None) -> str:
"""Find the configuration file: flag, then env, then the usual locations."""
if explicit:
return explicit
from_env = os.environ.get(CONFIG_PATH_ENV)
if from_env:
return from_env
for candidate in _DEFAULT_PATHS:
if Path(candidate).is_file():
return candidate
return _DEFAULT_PATHS[0]
def load_config(path: str | None = None) -> Config:
"""Load, interpolate and validate the configuration file."""
source = resolve_config_path(path)
raw_text = _read_config_text(source)
try:
document = json.loads(raw_text)
except json.JSONDecodeError as exc:
detail = f"not valid JSON: {exc.msg} (line {exc.lineno}, column {exc.colno})"
raise ConfigError([detail], source) from exc
if not isinstance(document, dict):
raise ConfigError(["the top level of the configuration must be a JSON object"], source)
base_dir = Path(source).resolve().parent
problems: list[str] = []
interpolated = _interpolate(document, "", base_dir, problems)
if problems:
raise ConfigError(problems, source)
if not isinstance(interpolated, dict): # pragma: no cover - shape is preserved
raise ConfigError(["internal error: configuration root is not an object"], source)
warnings: list[str] = []
validator = _Validator()
config = Config(
server=_build_server(validator, interpolated),
freshrss=_build_freshrss(validator, interpolated),
catalog=_build_catalog(validator, interpolated),
epub=_build_epub(validator, interpolated),
auth=_build_auth(validator, interpolated),
cache=_build_cache(validator, interpolated),
source_path=str(Path(source).resolve()),
warnings=warnings,
)
warnings.extend(_unknown_keys(interpolated, _KNOWN_KEYS))
if validator.problems:
raise ConfigError(validator.problems, source)
return config
def password_digest(password: str) -> str:
"""Digest a password for storage in ``auth.users[].password_sha256``."""
return hashlib.sha256(password.encode("utf-8")).hexdigest()
def normalise_api_base(url: str) -> str:
"""Normalise a FreshRSS URL to its Google Reader API base.
Mirrors the firmware client's rule so the same address works in both places:
the ``/api/greader.php`` suffix is appended when absent and left alone when
present, and any path prefix in between (``/freshrss``) is preserved.
"""
base = url.strip().rstrip("/")
if base.lower().endswith(GREADER_SUFFIX):
return base
return base + GREADER_SUFFIX
def describe_config(config: Config) -> str:
"""Render the effective configuration for logs, with secrets redacted."""
users = ", ".join(user.username for user in config.auth.users) or "(none)"
lines = [
f"config file: {config.source_path}",
f"listener: {config.server.host}:{config.server.port} "
f"(log level {config.server.log_level}"
+ (", TLS on" if config.server.tls_cert_file else "")
+ ")",
f"freshrss: {config.freshrss.api_base} as {config.freshrss.username} "
f"(password: {_mask(config.freshrss.api_password)}, mark read: "
f"{'yes' if config.freshrss.mark_read else 'no'})",
f"catalog: {config.catalog.title!r}, {config.freshrss.items_per_page} items/page, "
f"read section: {'yes' if config.catalog.show_read_section else 'no'}",
f"epub images: {'yes' if config.epub.include_images else 'no'}",
f"auth users: {users}",
]
return "\n".join(lines)
def _mask(secret: str) -> str:
if not secret:
return "(empty)"
return "***" if len(secret) <= 8 else f"***({len(secret)} chars)"
def _read_config_text(source: str) -> str:
try:
return Path(source).read_text(encoding="utf-8")
except FileNotFoundError as exc:
raise ConfigError(
[
f"configuration file not found: {source}",
f"set {CONFIG_PATH_ENV} or pass --config; "
"see config.example.json for a starting point",
],
source,
) from exc
except OSError as exc:
raise ConfigError([f"cannot read configuration file: {exc.strerror}"], source) from exc
# -- interpolation -------------------------------------------------------
def _interpolate(value: Any, path: str, base_dir: Path, problems: list[str]) -> Any:
"""Recursively expand ``${VAR}`` and ``${file:...}`` in every string."""
if isinstance(value, str):
return _interpolate_string(value, path, base_dir, problems)
if isinstance(value, dict):
return {
key: (
# A `_`-prefixed key is a comment: left exactly as written, so a
# comment that mentions ${SOMETHING} stays inert.
item
if key.startswith("_")
else _interpolate(item, f"{path}.{key}" if path else key, base_dir, problems)
)
for key, item in value.items()
}
if isinstance(value, list):
return [
_interpolate(item, f"{path}[{index}]", base_dir, problems)
for index, item in enumerate(value)
]
return value
def _interpolate_string(value: str, path: str, base_dir: Path, problems: list[str]) -> str:
if "${" not in value:
return value
# Protect an escaped literal `${` before scanning for real references.
text = value.replace("$${", _ESCAPED_DOLLAR + "{")
def replace(match: re.Match[str]) -> str:
expression = match.group(1).strip()
if expression.startswith("file:"):
return _read_secret_file(expression[len("file:") :].strip(), path, base_dir, problems)
name, separator, default = expression.partition(":-")
name = name.strip()
if not name:
problems.append(f"{path}: empty ${{}} reference")
return ""
found = os.environ.get(name)
if found is not None:
return found
if separator:
return default
problems.append(
f"{path}: environment variable {name} is not set (use ${{{name}:-default}} "
"to make it optional, or ${file:path} to read a secret from a file)"
)
return ""
result = _INTERPOLATION_RE.sub(replace, text)
return result.replace(_ESCAPED_DOLLAR + "{", "${")
def _read_secret_file(filename: str, path: str, base_dir: Path, problems: list[str]) -> str:
if not filename:
problems.append(f"{path}: ${{file:}} needs a path")
return ""
candidate = Path(filename)
if not candidate.is_absolute():
candidate = base_dir / candidate
try:
# Strip the trailing newline every secret-management tool adds.
return candidate.read_text(encoding="utf-8").strip()
except OSError as exc:
problems.append(f"{path}: cannot read secret file {candidate}: {exc.strerror}")
return ""
# -- validation ----------------------------------------------------------
class _Validator:
"""Collects type and range problems while building the config dataclasses.
Problems are qualified by the section being validated, so a message reads
``freshrss.url: required, but missing`` rather than the ambiguous
``url: required, but missing``. That matters as soon as two sections share a
key name, which they do (``timeout_seconds`` lives in three of them).
"""
def __init__(self) -> None:
self.problems: list[str] = []
self._prefix = ""
@contextmanager
def within(self, path: str) -> Iterator[None]:
"""Qualify every problem reported inside this block with ``path``."""
previous = self._prefix
self._prefix = f"{previous}.{path}" if previous else path
try:
yield
finally:
self._prefix = previous
def qualify(self, key: str | None = None) -> str:
"""Full path for a key, in the section currently being validated."""
if not key:
return self._prefix
return f"{self._prefix}.{key}" if self._prefix else key
def problem(self, message: str, key: str | None = None) -> None:
"""Report a problem against the current section, or against one key."""
location = self.qualify(key)
self.problems.append(f"{location}: {message}" if location else message)
def section(self, raw: dict[str, Any], name: str) -> dict[str, Any]:
value = raw.get(name)
if value is None:
return {}
if not isinstance(value, dict):
self.problem("must be a JSON object", key=name)
return {}
return value
def string(
self,
raw: dict[str, Any],
key: str,
default: str | None = None,
*,
required: bool = False,
) -> Any:
if key not in raw or raw[key] is None:
if required:
self.problem("required, but missing", key=key)
return default
value = raw[key]
if not isinstance(value, str):
self.problem("must be a string", key=key)
return default
text = value.strip()
if not text:
if required:
self.problem("required, but empty", key=key)
return default
return text
def one_of(self, raw: dict[str, Any], key: str, allowed: frozenset[str], default: str) -> str:
value = self.string(raw, key, default)
if value is None or value not in allowed:
self.problem(f"must be one of {', '.join(sorted(allowed))} (got {value!r})", key=key)
return default
return value
def boolean(self, raw: dict[str, Any], key: str, default: bool) -> bool:
if key not in raw or raw[key] is None:
return default
value = raw[key]
if not isinstance(value, bool):
self.problem("must be true or false", key=key)
return default
return value
def integer(
self,
raw: dict[str, Any],
key: str,
default: int,
*,
minimum: int | None = None,
maximum: int | None = None,
) -> int:
if key not in raw or raw[key] is None:
return default
value = raw[key]
# A bool is an int in Python; accepting it here would turn `true` into 1.
if isinstance(value, bool) or not isinstance(value, int):
self.problem("must be a whole number", key=key)
return default
if minimum is not None and value < minimum:
self.problem(f"must be at least {minimum} (got {value})", key=key)
return default
if maximum is not None and value > maximum:
self.problem(f"must be at most {maximum} (got {value})", key=key)
return default
return value
def number(self, raw: dict[str, Any], key: str, default: float, *, above: float = 0) -> float:
if key not in raw or raw[key] is None:
return default
value = raw[key]
if isinstance(value, bool) or not isinstance(value, (int, float)):
self.problem("must be a number", key=key)
return default
if value <= above:
self.problem(f"must be greater than {above:g} (got {value:g})", key=key)
return default
return float(value)
def string_list(self, raw: dict[str, Any], key: str) -> list[str]:
if key not in raw or raw[key] is None:
return []
value = raw[key]
if not isinstance(value, list):
self.problem("must be an array of strings", key=key)
return []
items: list[str] = []
for index, item in enumerate(value):
if not isinstance(item, str):
self.problem("must be a string", key=f"{key}[{index}]")
continue
if item.strip():
items.append(item.strip())
return items
def _build_server(validator: _Validator, raw: dict[str, Any]) -> ServerConfig:
section = validator.section(raw, "server")
with validator.within("server"):
with validator.within("tls"):
tls = validator.section(section, "tls")
cert = validator.string(tls, "cert_file")
key = validator.string(tls, "key_file")
if bool(cert) != bool(key):
validator.problem("cert_file and key_file must be set together")
elif cert:
_require_readable_file(validator, cert, "cert_file")
_require_readable_file(validator, key, "key_file")
return ServerConfig(
host=validator.string(section, "host", DEFAULT_BIND_HOST) or DEFAULT_BIND_HOST,
# Port 0 asks the operating system for a free port, which is what the test
# suite uses and what a socket-activated or ephemeral deployment wants.
port=validator.integer(section, "port", 8080, minimum=0, maximum=65535),
log_level=validator.one_of(section, "log_level", _LOG_LEVELS, "info"),
public_base_url=validator.string(section, "public_base_url"),
trust_proxy_headers=validator.boolean(section, "trust_proxy_headers", False),
allowed_hosts=[
host.lower() for host in validator.string_list(section, "allowed_hosts")
],
tls_cert_file=cert,
tls_key_file=key,
)
def _build_freshrss(validator: _Validator, raw: dict[str, Any]) -> FreshRSSConfig:
section = validator.section(raw, "freshrss")
with validator.within("freshrss"):
url = validator.string(section, "url", required=True)
if url and not url.lower().startswith(("http://", "https://")):
validator.problem(f"must start with http:// or https:// (got {url!r})", key="url")
username = validator.string(section, "username", required=True)
password = validator.string(section, "api_password", required=True)
ca_file = validator.string(section, "ca_file")
if ca_file:
_require_readable_file(validator, ca_file, "ca_file")
items_per_page = validator.integer(section, "items_per_page", 30, minimum=1, maximum=500)
max_items = validator.integer(
section, "max_items_per_request", 200, minimum=1, maximum=5000
)
if max_items < items_per_page:
validator.problem(
f"max_items_per_request ({max_items}) must be at least "
f"items_per_page ({items_per_page})"
)
return FreshRSSConfig(
api_base=normalise_api_base(url) if url else "",
username=username or "",
api_password=password or "",
verify_tls=validator.boolean(section, "verify_tls", True),
ca_file=ca_file,
timeout_seconds=validator.number(section, "timeout_seconds", 15.0),
retries=validator.integer(section, "retries", 2, minimum=0, maximum=10),
mark_read=validator.boolean(section, "mark_read", True),
items_per_page=items_per_page,
max_items_per_request=max_items,
read_window_items=validator.integer(
section, "read_window_items", 200, minimum=1, maximum=5000
),
max_content_bytes=validator.integer(
section, "max_content_bytes", 1_048_576, minimum=4096, maximum=67_108_864
),
)
def _build_catalog(validator: _Validator, raw: dict[str, Any]) -> CatalogConfig:
section = validator.section(raw, "catalog")
with validator.within("catalog"):
return CatalogConfig(
title=validator.string(section, "title", "FreshRSS OPDS") or "FreshRSS OPDS",
author=validator.string(section, "author", "FreshRSS") or "FreshRSS",
language=validator.string(section, "language", "en") or "en",
publisher=validator.string(section, "publisher"),
show_unread_counts=validator.boolean(section, "show_unread_counts", True),
show_read_section=validator.boolean(section, "show_read_section", True),
show_starred=validator.boolean(section, "show_starred", True),
hide_empty_categories=validator.boolean(section, "hide_empty_categories", False),
exclude_categories=validator.string_list(section, "exclude_categories"),
exclude_feeds=validator.string_list(section, "exclude_feeds"),
)
def _build_epub(validator: _Validator, raw: dict[str, Any]) -> EpubConfig:
section = validator.section(raw, "epub")
with validator.within("epub"):
stylesheet = validator.string(section, "stylesheet")
if stylesheet:
_require_readable_file(validator, stylesheet, "stylesheet")
return EpubConfig(
include_images=validator.boolean(section, "include_images", True),
allowed_image_hosts=[
host.lower() for host in validator.string_list(section, "allowed_image_hosts")
],
blocked_image_hosts=[
host.lower() for host in validator.string_list(section, "blocked_image_hosts")
],
max_images_per_article=validator.integer(
section, "max_images_per_article", 20, minimum=0, maximum=200
),
max_image_bytes=validator.integer(
section, "max_image_bytes", 2_097_152, minimum=1024, maximum=52_428_800
),
max_total_image_bytes=validator.integer(
section,
"max_total_image_bytes",
16_777_216,
minimum=1024,
maximum=268_435_456,
),
image_timeout_seconds=validator.number(section, "image_timeout_seconds", 10.0),
cover_image=validator.boolean(section, "cover_image", True),
include_source_link=validator.boolean(section, "include_source_link", True),
stylesheet=stylesheet,
max_epub_bytes=validator.integer(
section, "max_epub_bytes", 33_554_432, minimum=4096, maximum=268_435_456
),
)
def _build_auth(validator: _Validator, raw: dict[str, Any]) -> AuthConfig:
section = validator.section(raw, "auth")
users: list[AuthUser] = []
with validator.within("auth"):
raw_users = section.get("users")
if raw_users is None:
validator.problem(
"required -- this catalog serves your entire reading queue, so it "
"will not start without credentials "
"(generate a digest with: make hash-password)",
key="users",
)
elif not isinstance(raw_users, list):
validator.problem("must be an array of user objects", key="users")
elif not raw_users:
validator.problem("must contain at least one user", key="users")
else:
seen: set[str] = set()
for index, entry in enumerate(raw_users):
with validator.within(f"users[{index}]"):
users.append(_build_auth_user(validator, entry, seen))
return AuthConfig(
realm=validator.string(section, "realm", "OPDS") or "OPDS",
users=users,
max_failures_per_minute=validator.integer(
section, "max_failures_per_minute", 10, minimum=1, maximum=10_000
),
throttle_seconds=validator.number(section, "throttle_seconds", 60.0),
)
def _build_auth_user(validator: _Validator, entry: Any, seen: set[str]) -> AuthUser:
"""Build one user; the caller has already entered its ``users[i]`` context."""
if not isinstance(entry, dict):
validator.problem("must be a JSON object")
return AuthUser("", "")
username = validator.string(entry, "username", required=True) or ""
if username and username in seen:
validator.problem(f"duplicate username {username!r}", key="username")
seen.add(username)
plain = _validated_plain_password(validator, entry)
digest = _validated_digest(validator, entry)
if plain is not None and digest is not None:
validator.problem("set either password or password_sha256, not both")
return AuthUser(username, "")
if digest is not None:
return AuthUser(username, digest)
if plain is not None:
LOGGER.warning(
"%s.password is in clear text in the configuration file; "
"prefer password_sha256 (make hash-password)",
validator.qualify(),
)
return AuthUser(username, password_digest(plain))
validator.problem("needs password or password_sha256")
return AuthUser(username, "")
def _validated_plain_password(validator: _Validator, entry: dict[str, Any]) -> str | None:
"""Return a clear-text password from config, or None when absent/invalid."""
value = entry.get("password")
if value is None:
return None
if not isinstance(value, str) or not value:
validator.problem("must be a non-empty string", key="password")
return None
return value
def _validated_digest(validator: _Validator, entry: dict[str, Any]) -> str | None:
"""Return a validated sha256 digest from config, or None when absent/invalid."""
value = entry.get("password_sha256")
if value is None:
return None
if not isinstance(value, str) or not _SHA256_RE.match(value):
validator.problem("must be 64 hex characters (make hash-password)", key="password_sha256")
return None
return value.lower()
def _build_cache(validator: _Validator, raw: dict[str, Any]) -> CacheConfig:
section = validator.section(raw, "cache")
with validator.within("cache"):
return CacheConfig(
subscriptions_ttl_seconds=validator.number(section, "subscriptions_ttl_seconds", 300.0),
stream_ttl_seconds=validator.number(section, "stream_ttl_seconds", 60.0),
item_ttl_seconds=validator.number(section, "item_ttl_seconds", 900.0),
max_entries=validator.integer(section, "max_entries", 512, minimum=16, maximum=100_000),
)
def _require_readable_file(validator: _Validator, filename: str, key: str) -> None:
if not Path(filename).is_file():
validator.problem(f"no such file: {filename}", key=key)
_KNOWN_KEYS: dict[str, set[str]] = {
"server": {
"host",
"port",
"log_level",
"public_base_url",
"trust_proxy_headers",
"allowed_hosts",
"tls",
},
"server.tls": {"cert_file", "key_file"},
"freshrss": {
"url",
"username",
"api_password",
"verify_tls",
"ca_file",
"timeout_seconds",
"retries",
"mark_read",
"items_per_page",
"max_items_per_request",
"read_window_items",
"max_content_bytes",
},
"catalog": {
"title",
"author",
"language",
"publisher",
"show_unread_counts",
"show_read_section",
"show_starred",
"hide_empty_categories",
"exclude_categories",
"exclude_feeds",
},
"epub": {
"include_images",
"allowed_image_hosts",
"blocked_image_hosts",
"max_images_per_article",
"max_image_bytes",
"max_total_image_bytes",
"image_timeout_seconds",
"cover_image",
"include_source_link",
"stylesheet",
"max_epub_bytes",
},
"auth": {"realm", "users", "max_failures_per_minute", "throttle_seconds"},
"auth.users[]": {"username", "password", "password_sha256"},
"cache": {
"subscriptions_ttl_seconds",
"stream_ttl_seconds",
"item_ttl_seconds",
"max_entries",
},
}
def _unknown_keys(document: dict[str, Any], known: dict[str, set[str]]) -> list[str]:
"""Report keys the server would otherwise silently ignore."""
warnings: list[str] = []
sections = {name for name in known if "." not in name}
for key in document:
if key in sections or key.startswith("_"):
continue
suggestions = _closest(key, sections)
hint = f" (did you mean {suggestions}?)" if suggestions else ""
warnings.append(f"{key}: unknown top-level setting, ignored{hint}")
for section, allowed in known.items():
if "." in section:
continue
value = document.get(section)
if not isinstance(value, dict):
continue
for key in value:
if key not in allowed and not key.startswith("_"):
suggestions = _closest(key, allowed)
hint = f" (did you mean {suggestions}?)" if suggestions else ""
warnings.append(f"{section}.{key}: unknown setting, ignored{hint}")
if section == "server" and isinstance(value.get("tls"), dict):
for key in value["tls"]:
if key not in known["server.tls"] and not key.startswith("_"):
warnings.append(f"server.tls.{key}: unknown setting, ignored")
if section == "auth" and isinstance(value.get("users"), list):
for index, entry in enumerate(value["users"]):
if not isinstance(entry, dict):
continue
for key in entry:
if key not in known["auth.users[]"] and not key.startswith("_"):
warnings.append(f"auth.users[{index}].{key}: unknown setting, ignored")
return warnings
def _closest(key: str, candidates: set[str]) -> str:
"""Suggest a near-miss key name, cheaply."""
lowered = key.lower().replace("-", "_")
for candidate in sorted(candidates):
if candidate.lower().replace("-", "_") == lowered:
return repr(candidate)
for candidate in sorted(candidates):
if candidate.lower().startswith(lowered[:4]) and len(lowered) >= 4:
return repr(candidate)
return ""