842 lines
32 KiB
Python
842 lines
32 KiB
Python
"""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 ""
|