"""Identifier, slug and URL helpers. FreshRSS ids do not survive a URL path or a Content-Disposition filename unharmed. Item ids look like ``tag:google.com,2005:reader/item/0000000000000abc`` and stream ids look like ``feed/https://example.com/atom.xml?x=1``, so both carry characters that are structural in a path (``/``, ``?``, ``#``) and are long enough to blow past filename limits. The rule this module enforces: every opaque id that appears in a path is base64url-encoded, and the human-readable part of a download URL is a slug that the server ignores when it looks the item up. That keeps routes unambiguous without any escaping tricks, and lets a reader name the saved file sensibly. """ from __future__ import annotations import base64 import binascii import re import unicodedata import uuid # Fixed namespace for every derived urn:uuid in this server. Hardcoded so that # feed and entry ids stay stable across restarts and across hostnames -- a client # that cached an entry id must still recognise it tomorrow. _UUID_NAMESPACE = uuid.UUID("b7437da1-d469-46b1-a582-0af386fadb9d") _B64URL_RE = re.compile(r"\A[A-Za-z0-9_-]+\Z") # Everything that is not an ASCII lowercase letter or digit becomes a dash, so # the result is safe in a path segment, a filename, and a shell. _SLUG_JUNK_RE = re.compile(r"[^a-z0-9]+") def b64url_encode(value: str) -> str: """Encode a UTF-8 string as unpadded base64url (path-segment safe).""" raw = value.encode("utf-8") return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii") def b64url_decode(value: str) -> str: """Decode an unpadded base64url string, raising ValueError on junk. Strict on purpose: this parses untrusted path input, so anything that is not a well-formed unpadded base64url token -- or that decodes to something other than UTF-8 -- is rejected instead of being coerced. """ if not value or not _B64URL_RE.match(value): raise ValueError("not a base64url token") padding = "=" * (-len(value) % 4) try: raw = base64.urlsafe_b64decode(value + padding) except (binascii.Error, ValueError) as exc: raise ValueError("not a base64url token") from exc try: return raw.decode("utf-8") except UnicodeDecodeError as exc: raise ValueError("base64url token is not UTF-8") from exc def slugify(text: str, max_length: int = 60) -> str: """Reduce a title to a conservative filename slug. Accented characters are folded to ASCII rather than dropped, non-ASCII scripts fall back to ``article``, and the result is length-capped because a filesystem name is the eventual destination. """ folded = unicodedata.normalize("NFKD", text or "") ascii_text = folded.encode("ascii", "ignore").decode("ascii") slug = _SLUG_JUNK_RE.sub("-", ascii_text.lower()).strip("-") if len(slug) > max_length: slug = slug[:max_length].rstrip("-") return slug or "article" def stable_urn(kind: str, value: str) -> str: """Return a deterministic ``urn:uuid`` for a feed, entry or item. Atom requires every feed and entry to carry a permanent id. Deriving it from the FreshRSS id rather than from the request URL means the same article keeps one identity no matter which category path the reader reached it through. """ derived = uuid.uuid5(_UUID_NAMESPACE, f"{kind}:{value}") return f"urn:uuid:{derived}" def content_disposition(ascii_name: str, unicode_name: str | None = None) -> str: """Build an attachment Content-Disposition with an RFC 5987 fallback. Every OPDS reader understands ``filename``; readers that save a title with non-ASCII characters need ``filename*``. Sending both is the only way to get a correct name everywhere, so both are always emitted. """ ascii_name = ascii_name.replace('"', "").replace("\\", "") or "article.epub" header = f'attachment; filename="{ascii_name}"' if unicode_name and unicode_name != ascii_name: encoded = _quote_rfc5987(unicode_name.replace('"', "").replace("\\", "")) if encoded: header += f"; filename*=UTF-8''{encoded}" return header def _quote_rfc5987(value: str) -> str: out = [] for byte in value.encode("utf-8"): char = chr(byte) if char.isalnum() and byte < 0x80 or char in "-._~": out.append(char) else: out.append(f"%{byte:02X}") return "".join(out) def join_url(base: str, *parts: str) -> str: """Join URL path parts onto a base, collapsing duplicate slashes.""" segments = [base.rstrip("/")] for part in parts: cleaned = part.strip("/") if cleaned: segments.append(cleaned) return "/".join(segments)