Coverage for downtify/trash_routes.py: 78%

241 statements  

« prev     ^ index     » next       coverage.py v7.17.4, created at 2026-11-21 22:18 +0000

1"""One administrator-only trash API for browsers and paired applications.""" 

2 

3from __future__ import annotations 

4 

5import asyncio 

6import secrets 

7import time 

8 

9from fastapi import APIRouter, HTTPException, Query, Request 

10from loguru import logger 

11from pydantic import BaseModel, Field 

12 

13from . import api, lyrics 

14from .admin_access import admin_user 

15from .library_catalog import list_library_entries 

16from .library_paths import library_file_root 

17from .library_paths_cache import invalidate_library_paths_cache 

18from .library_trash import RETENTION_DAYS, LibraryTrash, TrashError 

19 

20router = APIRouter(prefix='/api/v1/library/trash') 

21 

22 

23class Selection(BaseModel): 

24 files: list[str] = Field(default_factory=list, max_length=200) 

25 track_ids: list[str] = Field(default_factory=list, max_length=200) 

26 

27 

28class Confirmation(BaseModel): 

29 confirmation: str = Field(min_length=20, max_length=100) 

30 

31 

32class Items(BaseModel): 

33 ids: list[str] = Field(min_length=1, max_length=200) 

34 

35 

36_previews = {} 

37_preview_slots = asyncio.Semaphore(1) 

38_PREVIEW_JOB_TTL = 3600 

39#: How often the watcher looks for work and for a separate worker's 

40#: progress, unless a request wakes it sooner. 

41_WATCH_SECONDS = 2.0 

42#: Operations one embedded worker pass handles before the library is 

43#: refreshed and the next pass starts. 

44_WORKER_BATCH = 10 

45_wake: asyncio.Event | None = None 

46 

47 

48def _clean_preview_jobs(): 

49 now = time.monotonic() 

50 for key, job in list(_previews.items()): 

51 if ( 

52 job['state'] != 'preparing' 

53 and now - job['created'] > _PREVIEW_JOB_TTL 

54 ): 

55 _previews.pop(key, None) 

56 

57 

58def _prepare_preview(payload: Selection, user_id: int): 

59 tracks = _selection(payload) 

60 current = api.state.auth.users.get(user_id) if api.state.auth else None 

61 if current is None or current.get('role') != 'admin': 

62 raise TrashError('admin_access_revoked') 

63 return store().preview(user_id, tracks) 

64 

65 

66async def _run_preview(job_id: str, payload: Selection, user_id: int): 

67 async with _preview_slots: 

68 try: 

69 result = await asyncio.to_thread( 

70 _prepare_preview, payload, user_id 

71 ) 

72 _previews[job_id].update(state='ready', preview=result) 

73 except TrashError as error: 

74 _previews[job_id].update(state='failed', error=str(error)) 

75 except OSError: 

76 _previews[job_id].update( 

77 state='failed', error='filesystem_unavailable' 

78 ) 

79 except Exception as error: 

80 logger.warning('Trash preview failed ({})', type(error).__name__) 

81 _previews[job_id].update(state='failed', error='unavailable') 

82 

83 

84def store() -> LibraryTrash: 

85 value = getattr(api.state, 'library_trash', None) 

86 if value is None: 

87 raise HTTPException(503, detail={'code': 'trash_not_configured'}) 

88 return value 

89 

90 

91async def call(function, *args, **kwargs): 

92 try: 

93 return await asyncio.to_thread(function, *args, **kwargs) 

94 except TrashError as exc: 

95 raise HTTPException(409, detail={'code': str(exc)}) from None 

96 except OSError: 

97 raise HTTPException( 

98 503, detail={'code': 'filesystem_unavailable'} 

99 ) from None 

100 

101 

102def _selection(payload: Selection) -> list[dict]: 

103 ctx = api.library_context() 

104 entries = {entry['file']: entry for entry in list_library_entries(ctx)} 

105 files = list(payload.files) 

106 for track_id in payload.track_ids: 

107 row = ( 

108 api.state.library_sync.row_for(track_id) 

109 if api.state.library_sync 

110 else None 

111 ) 

112 if row is None: 

113 raise TrashError('item_not_found') 

114 files.append(row['file']) 

115 files = list(dict.fromkeys(files)) 

116 if not files or len(files) > 200: 

117 raise TrashError('invalid_selection') 

118 ensure_idle(files) 

119 ids = ( 

120 api.state.library_sync.ids_for_paths(files) 

121 if api.state.library_sync 

122 else {} 

123 ) 

124 selected = [] 

125 for file in files: 

126 if file not in entries: 

127 raise TrashError('item_not_found') 

128 root, relative = library_file_root( 

129 file, ctx.download_dir, ctx.slskd_dir, ctx.extra_dirs 

130 ) 

131 key = next( 

132 ( 

133 key 

134 for key, value in store().roots.items() 

135 if value.path.resolve() == root.resolve() 

136 ), 

137 None, 

138 ) 

139 if key is None: 

140 raise TrashError('unsupported_collection') 

141 metadata = dict(entries[file]) 

142 if api.state.track_index is not None: 

143 spotify_id = api.state.track_index.spotify_id_for_filename(file) 

144 if spotify_id: 

145 metadata['spotify_id'] = spotify_id 

146 extra_sidecars = [] 

147 audio_path = root / relative 

148 configured_lrc = lyrics.lrc_sidecar_path( 

149 audio_path, 

150 settings=api.state.settings, 

151 download_dir=ctx.download_dir, 

152 slskd_dir=ctx.slskd_dir, 

153 extra_dirs=ctx.extra_dirs, 

154 ) 

155 if configured_lrc != audio_path.with_suffix('.lrc') and ( 

156 configured_lrc.exists() or configured_lrc.is_symlink() 

157 ): 

158 lrc_key = next( 

159 ( 

160 name 

161 for name, value in store().roots.items() 

162 if configured_lrc.absolute().is_relative_to( 

163 value.path.absolute() 

164 ) 

165 ), 

166 None, 

167 ) 

168 if lrc_key is None: 

169 raise TrashError('unsupported_lyrics_location') 

170 extra_sidecars.append({ 

171 'root_key': lrc_key, 

172 'relative': configured_lrc 

173 .absolute() 

174 .relative_to(store().roots[lrc_key].path.absolute()) 

175 .as_posix(), 

176 }) 

177 selected.append({ 

178 'stored': file, 

179 'root_key': key, 

180 'relative': relative, 

181 'track_id': ids.get(file, ''), 

182 'metadata': metadata, 

183 'extra_sidecars': extra_sidecars, 

184 }) 

185 return selected 

186 

187 

188def ensure_idle(files: list[str]): 

189 active = { 

190 str(p.get('track', {}).get('file') or '') 

191 for p in api.state.now_playing.active() 

192 if not p.get('paused', False) 

193 } 

194 if active.intersection(files): 

195 raise TrashError('track_is_playing') 

196 runner = getattr(api.state, 'upgrade_runner', None) 

197 if runner is not None: 

198 status = runner.status() 

199 if status.get('state') in { 

200 'running', 

201 'scanning', 

202 'pausing', 

203 } or status.get('counts', {}).get('running', 0): 

204 raise TrashError('library_task_active') 

205 

206 

207@router.get('/capabilities') 

208def capabilities(request: Request): 

209 enabled = getattr(api.state, 'library_trash', None) is not None 

210 try: 

211 admin_user(request) 

212 except HTTPException: 

213 admin = False 

214 else: 

215 admin = True 

216 return { 

217 'can_manage': enabled and admin, 

218 'enabled': enabled, 

219 'retention_days': RETENTION_DAYS, 

220 } 

221 

222 

223@router.post('/preview', status_code=202) 

224async def preview(payload: Selection, request: Request): 

225 user = admin_user(request) 

226 store() 

227 if not payload.files and not payload.track_ids: 

228 raise HTTPException(409, detail={'code': 'invalid_selection'}) 

229 _clean_preview_jobs() 

230 if any( 

231 j['user_id'] == user and j['state'] == 'preparing' 

232 for j in _previews.values() 

233 ): 

234 raise HTTPException(409, detail={'code': 'preview_busy'}) 

235 if sum(j['state'] == 'preparing' for j in _previews.values()) >= 4: 

236 raise HTTPException(429, detail={'code': 'preview_busy'}) 

237 job_id = secrets.token_urlsafe(32) 

238 _previews[job_id] = { 

239 'user_id': user, 

240 'state': 'preparing', 

241 'created': time.monotonic(), 

242 } 

243 api.spawn_task(_run_preview(job_id, payload, user), name='trash-preview') 

244 return {'request_id': job_id, 'state': 'preparing'} 

245 

246 

247@router.get('/preview/{job_id}') 

248async def preview_status(job_id: str, request: Request): 

249 user = admin_user(request) 

250 _clean_preview_jobs() 

251 job = _previews.get(job_id) 

252 if job is None or job['user_id'] != user: 

253 raise HTTPException(404, detail={'code': 'preview_unavailable'}) 

254 if job['state'] == 'failed': 

255 raise HTTPException(409, detail={'code': job['error']}) 

256 if job['state'] == 'ready': 

257 return {'state': 'ready', 'preview': job['preview']} 

258 return {'state': 'preparing'} 

259 

260 

261@router.post('/confirm', status_code=202) 

262async def confirm(payload: Confirmation, request: Request): 

263 user = admin_user(request) 

264 files = await call(store().confirmation_files, user, payload.confirmation) 

265 await call(ensure_idle, files) 

266 ids = await call(store().confirm, user, payload.confirmation) 

267 await publish_changes() 

268 wake_worker() 

269 await api.log_activity(request, 'library_trash_requested', str(len(ids))) 

270 return {'ids': ids, 'state': 'pending'} 

271 

272 

273@router.get('') 

274async def listing( 

275 request: Request, 

276 offset: int = Query(0, ge=0), 

277 limit: int = Query(50, ge=1, le=100), 

278 search: str = Query('', max_length=200), 

279): 

280 admin_user(request) 

281 await publish_changes() 

282 return await call(store().list, offset=offset, limit=limit, search=search) 

283 

284 

285@router.get('/exclusions') 

286async def exclusions(request: Request): 

287 admin_user(request) 

288 return {'items': await call(store().exclusions)} 

289 

290 

291@router.post('/restore', status_code=202) 

292async def restore(payload: Items, request: Request): 

293 user = admin_user(request) 

294 await call(store().request_restore, payload.ids, user_id=user) 

295 wake_worker() 

296 await api.log_activity( 

297 request, 'library_trash_restore_requested', str(len(payload.ids)) 

298 ) 

299 return {'state': 'restore_pending'} 

300 

301 

302@router.post('/allow-download') 

303async def allow_download(payload: Items, request: Request): 

304 admin_user(request) 

305 await call(store().allow_download, payload.ids) 

306 await publish_changes() 

307 return {'ok': True} 

308 

309 

310@router.post('/retry', status_code=202) 

311async def retry(payload: Items, request: Request): 

312 user = admin_user(request) 

313 await call(store().retry, payload.ids, user_id=user) 

314 wake_worker() 

315 return {'state': 'pending'} 

316 

317 

318_revision = None 

319 

320 

321async def publish_changes(): 

322 global _revision 

323 value = getattr(api.state, 'library_trash', None) 

324 if value is None: 

325 return 

326 revision = await asyncio.to_thread(value.revision) 

327 if revision == _revision: 

328 return 

329 invalidate_library_paths_cache(drop_entries=True) 

330 if api.state.library_visibility is not None: 

331 api.state.library_visibility.invalidate() 

332 if api.state.library_sync is not None: 

333 await asyncio.to_thread( 

334 lambda: api.state.library_sync.refresh( 

335 list_library_entries(api.library_context()) 

336 ) 

337 ) 

338 api.announce_library_changed() 

339 await api.announce_playlists_changed() 

340 _revision = revision 

341 

342 

343def wake_worker() -> None: 

344 """Run the watcher now: a request just queued work for it.""" 

345 

346 if _wake is not None: 

347 _wake.set() 

348 

349 

350def _still_admin(user_id: int) -> bool: 

351 auth = api.state.auth 

352 user = auth.users.get(user_id) if auth is not None and user_id else None 

353 return user is not None and user.get('role') == 'admin' 

354 

355 

356def _held_back(trash: LibraryTrash) -> frozenset[str] | None: 

357 """Operations that must wait: the ones on a song playing right now, 

358 or all of them while the library upgrade rewrites files (``None``).""" 

359 

360 try: 

361 ensure_idle([]) 

362 except TrashError: 

363 return None 

364 playing = { 

365 str(p.get('track', {}).get('file') or '') 

366 for p in api.state.now_playing.active() 

367 if not p.get('paused', False) 

368 } 

369 return frozenset( 

370 item for item, file in trash.work_files().items() if file in playing 

371 ) 

372 

373 

374def run_worker_pass(trash: LibraryTrash) -> list[dict]: 

375 """One bounded pass of the embedded worker (in a thread).""" 

376 

377 if trash.worker != 'embedded' or not trash.has_work(): 

378 return [] 

379 skip = _held_back(trash) 

380 if skip is None: 

381 return [] 

382 done = trash.process( 

383 limit=_WORKER_BATCH, authorized=_still_admin, skip_ids=skip 

384 ) 

385 for row in done: 

386 if not row['ok']: 

387 logger.warning( 

388 'Trash operation {} stopped: {}', row['id'], row['error'] 

389 ) 

390 return done 

391 

392 

393async def watch_trash(): 

394 """Publish the journal's changes to the library and, with the 

395 embedded worker, carry out the queued moves, restores and expiries.""" 

396 

397 global _wake 

398 _wake = asyncio.Event() 

399 while True: 

400 done = [] 

401 try: 

402 trash = getattr(api.state, 'library_trash', None) 

403 if trash is not None and trash.worker == 'embedded': 

404 done = await asyncio.to_thread(run_worker_pass, trash) 

405 await publish_changes() 

406 except Exception as error: 

407 logger.warning( 

408 'Trash synchronization deferred ({})', type(error).__name__ 

409 ) 

410 if done: 

411 continue # more may be waiting: don't sit out the interval 

412 try: 

413 await asyncio.wait_for(_wake.wait(), _WATCH_SECONDS) 

414 except asyncio.TimeoutError: 

415 pass 

416 _wake.clear()