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

1"""Bundle selected library files into one ZIP download. 

2 

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. 

6 

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. 

13 

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""" 

19 

20from __future__ import annotations 

21 

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 

30 

31from loguru import logger 

32 

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 

37 

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 

42 

43#: Bytes buffered before a chunk is yielded to the response. 

44_CHUNK_SIZE = 256 * 1024 

45 

46 

47class _StreamBuffer: 

48 """Write target for :class:`zipfile.ZipFile` over a stream. 

49 

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 """ 

54 

55 def __init__(self) -> None: 

56 self._parts: list[bytes] = [] 

57 self._pending = 0 

58 self.offset = 0 

59 

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) 

65 

66 def tell(self) -> int: 

67 return self.offset 

68 

69 @staticmethod 

70 def flush() -> None: 

71 """No-op: ``ZipFile`` flushes its output; chunks are drained.""" 

72 

73 def has_chunk(self) -> bool: 

74 return self._pending >= _CHUNK_SIZE 

75 

76 def drain(self) -> bytes: 

77 data = b''.join(self._parts) 

78 self._parts.clear() 

79 self._pending = 0 

80 return data 

81 

82 

83def archive_filename(now: datetime | None = None) -> str: 

84 """Name for the downloaded ZIP, stamped so repeats don't collide.""" 

85 

86 moment = now or datetime.now(timezone.utc).astimezone() 

87 return f'downtify-library-{moment.strftime("%Y%m%d-%H%M%S")}.zip' 

88 

89 

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. 

97 

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 """ 

101 

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() 

111 

112 

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. 

117 

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 """ 

123 

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) 

144 

145 

146class ArchiveTicketStore: 

147 """Short-lived, single-use tickets for prepared archive selections.""" 

148 

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]]]] = {} 

153 

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 

160 

161 def pop(self, token: str) -> list[tuple[str, Path]] | None: 

162 """Claim a ticket. ``None`` when unknown, already used or expired.""" 

163 

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] 

170 

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]