121 lines
4.6 KiB
Python
121 lines
4.6 KiB
Python
"""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)
|