Initial commit
This commit is contained in:
841
app/config.py
Normal file
841
app/config.py
Normal 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 ""
|
||||
Reference in New Issue
Block a user