Coverage for downtify/library_archive.py: 99%
86 statements
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
1"""Bundle selected library files into one ZIP download.
3The Library page's multi-select can cover hundreds of tracks, and
4saving them to the machine in front of the user meant clicking the
5download icon once per track. This builds a single ZIP instead.
7The archive is streamed as it is built: entries are *stored*, not
8deflated (audio files don't compress), and each chunk is handed to the
9response as soon as it exists, so a multi-gigabyte selection never
10lands in the server's memory or in a temp file. Because the size isn't
11known up front, the response has no ``Content-Length`` — browsers show
12the download without a progress percentage.
14Selections are handed out as short-lived, single-use tickets: the file
15list arrives in a POST body (a few hundred paths don't fit in a URL),
16and the ticket is what the browser then navigates to so the download
17lands in the user's download folder like any other file.
18"""
20from __future__ import annotations
22import os
23import secrets
24import time
25import zipfile
26from collections.abc import Iterable, Iterator
27from datetime import datetime, timezone
28from pathlib import Path
29from threading import Lock
31from loguru import logger
33#: Hard cap on one archive request, mirroring the batch-delete cap in
34#: ``main.py``: an accidental "select everything" on a huge library
35#: shouldn't build a ZIP nobody can use.
36MAX_ARCHIVE_FILES = 2000
38#: How long a prepared selection stays downloadable. Long enough for a
39#: slow browser to follow the redirect, short enough that abandoned
40#: tickets don't pile up.
41TICKET_TTL_SECONDS = 300
43#: Bytes buffered before a chunk is yielded to the response.
44_CHUNK_SIZE = 256 * 1024
47class _StreamBuffer:
48 """Write target for :class:`zipfile.ZipFile` over a stream.
50 ``ZipFile`` needs ``write``/``tell``/``flush``; without ``seek`` it
51 writes data descriptors instead of rewinding to patch headers,
52 which is exactly what a streamed archive needs.
53 """
55 def __init__(self) -> None:
56 self._parts: list[bytes] = []
57 self._pending = 0
58 self.offset = 0
60 def write(self, data: bytes) -> int:
61 self._parts.append(bytes(data))
62 self._pending += len(data)
63 self.offset += len(data)
64 return len(data)
66 def tell(self) -> int:
67 return self.offset
69 @staticmethod
70 def flush() -> None:
71 """No-op: ``ZipFile`` flushes its output; chunks are drained."""
73 def has_chunk(self) -> bool:
74 return self._pending >= _CHUNK_SIZE
76 def drain(self) -> bytes:
77 data = b''.join(self._parts)
78 self._parts.clear()
79 self._pending = 0
80 return data
83def archive_filename(now: datetime | None = None) -> str:
84 """Name for the downloaded ZIP, stamped so repeats don't collide."""
86 moment = now or datetime.now(timezone.utc).astimezone()
87 return f'downtify-library-{moment.strftime("%Y%m%d-%H%M%S")}.zip'
90def _entry_chunks(
91 archive: zipfile.ZipFile,
92 buffer: _StreamBuffer,
93 name: str,
94 path: Path,
95) -> Iterator[bytes]:
96 """Copy one file into the archive, yielding buffered chunks.
98 The source is opened before the archive entry, so a file that can't
99 be read at all never leaves a stray entry behind.
100 """
102 with path.open('rb') as source:
103 info = zipfile.ZipInfo(name)
104 # Choose ZIP64 before emitting the header; a stream cannot rewind it.
105 info.file_size = os.fstat(source.fileno()).st_size
106 with archive.open(info, mode='w') as target:
107 while chunk := source.read(_CHUNK_SIZE):
108 target.write(chunk)
109 if buffer.has_chunk():
110 yield buffer.drain()
113def stream_library_zip(
114 entries: Iterable[tuple[str, Path]],
115) -> Iterator[bytes]:
116 """Yield the bytes of a ZIP holding every ``(name, path)`` entry.
118 ``name`` is the path the file keeps inside the archive - the
119 library path, so per-playlist and artist/album folders survive the
120 round trip. Unreadable files are skipped rather than failing the
121 whole download, which is already in progress by then.
122 """
124 buffer = _StreamBuffer()
125 written = 0
126 with zipfile.ZipFile(
127 buffer, mode='w', compression=zipfile.ZIP_STORED, allowZip64=True
128 ) as archive:
129 for name, path in entries:
130 try:
131 yield from _entry_chunks(archive, buffer, name, path)
132 except (OSError, ValueError):
133 logger.opt(exception=True).warning(
134 'Library archive: skipping unreadable file {}', path
135 )
136 continue
137 written += 1
138 if buffer.has_chunk():
139 yield buffer.drain()
140 remainder = buffer.drain()
141 if remainder:
142 yield remainder
143 logger.info('Library archive: streamed {} file(s)', written)
146class ArchiveTicketStore:
147 """Short-lived, single-use tickets for prepared archive selections."""
149 def __init__(self, ttl_seconds: int = TICKET_TTL_SECONDS) -> None:
150 self._ttl = ttl_seconds
151 self._lock = Lock()
152 self._tickets: dict[str, tuple[float, list[tuple[str, Path]]]] = {}
154 def create(self, entries: list[tuple[str, Path]]) -> str:
155 token = secrets.token_urlsafe(16)
156 with self._lock:
157 self._prune()
158 self._tickets[token] = (time.monotonic(), list(entries))
159 return token
161 def pop(self, token: str) -> list[tuple[str, Path]] | None:
162 """Claim a ticket. ``None`` when unknown, already used or expired."""
164 with self._lock:
165 self._prune()
166 found = self._tickets.pop(token, None)
167 if found is None:
168 return None
169 return found[1]
171 def _prune(self) -> None:
172 cutoff = time.monotonic() - self._ttl
173 for token, (created, _) in list(self._tickets.items()):
174 if created < cutoff:
175 del self._tickets[token]