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

120
app/urls.py Normal file
View File

@@ -0,0 +1,120 @@
"""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)