image-optimizer-webui 1.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,3929 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import fnmatch
5
+ import hashlib
6
+ import json
7
+ import os
8
+ import secrets
9
+ import shutil
10
+ import socket
11
+ import subprocess
12
+ import sys
13
+ import tempfile
14
+ import time
15
+ from contextlib import asynccontextmanager
16
+ from pathlib import Path
17
+ from typing import Any, Awaitable, Callable, List, Optional
18
+ from zipfile import ZipFile
19
+
20
+ from fastapi import Depends, FastAPI, File, Header, HTTPException, UploadFile, Request
21
+ from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, Response, StreamingResponse
22
+ from PIL import Image, features as pil_features
23
+
24
+ if __package__ is None:
25
+ sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
26
+
27
+ from image_optimizer import binaries
28
+ from image_optimizer.cache import (
29
+ CACHEABLE_FORMATS,
30
+ DEFAULT_CACHE_MAX_MB,
31
+ ContentCache,
32
+ encoder_fingerprint,
33
+ is_valid_reusable_output as _is_valid_reusable_output,
34
+ settings_fingerprint as _settings_fingerprint,
35
+ )
36
+ from image_optimizer.models import OptimizeRequest, PreviewRequest, RecentClearRequest, RecentRemoveRequest, RevealRequest, ScanRequest, WatchRequest
37
+ from image_optimizer.optimizer import HEX_COLOR_RE, Optimizer
38
+ from image_optimizer.watcher import FolderWatcher
39
+
40
+ if getattr(sys, "frozen", False):
41
+ BASE_DIR = Path(sys._MEIPASS) / "image_optimizer"
42
+ else:
43
+ BASE_DIR = Path(__file__).resolve().parent
44
+
45
+
46
+ def _find_free_port(host: str, start: int, max_attempts: int = 10) -> int:
47
+ # NOTE: this is inherently a probe — there's a small TOCTOU window
48
+ # between closing the probe socket and uvicorn binding the real one.
49
+ # SO_REUSEADDR (non-Windows only: on Windows it means "steal the port",
50
+ # not "ignore TIME_WAIT") keeps a lingering TIME_WAIT from a previous
51
+ # run from making the probe reject a port uvicorn could bind just fine.
52
+ for port in range(start, start + max_attempts):
53
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
54
+ if sys.platform != "win32":
55
+ s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
56
+ try:
57
+ s.bind((host, port))
58
+ return port
59
+ except OSError:
60
+ continue
61
+ raise RuntimeError(f"No free port found in range {start}-{start + max_attempts - 1}")
62
+
63
+
64
+ WORKSPACE_CLEANUP_DELAY = 10.0 # seconds
65
+
66
+
67
+ async def _async_rmtree(path: Path):
68
+ """shutil.rmtree off the event loop. Recursive directory delete is a
69
+ synchronous syscall that scales with the number of files in the tree —
70
+ a workspace with thousands of thumbnails can take long enough to stall
71
+ every other async co-routine in the process (progress polls, thumbnail
72
+ workers, other sessions' scans). Anything the server itself triggers
73
+ in an async context should go through here rather than calling
74
+ shutil.rmtree directly.
75
+
76
+ The AppState.new_workspace no-event-loop fallback (synchronous path
77
+ during CLI startup) deliberately does NOT use this — there's no
78
+ running loop to `to_thread` onto, and nothing else is concurrent to
79
+ be stalled by it anyway.
80
+ """
81
+ await asyncio.to_thread(shutil.rmtree, path, ignore_errors=True)
82
+
83
+
84
+ async def _delayed_rmtree(path: Path):
85
+ """Give any in-flight requests reading from `path` a chance to finish
86
+ before actually deleting it. Not a hard guarantee (an unusually slow
87
+ download could still lose a race), but turns a zero-grace-period bug
88
+ into one that needs a multi-second coincidence to hit."""
89
+ await asyncio.sleep(WORKSPACE_CLEANUP_DELAY)
90
+ await _async_rmtree(path)
91
+
92
+
93
+ class AppState:
94
+ def __init__(self):
95
+ self.files: list = []
96
+ self.results: list = []
97
+ self.input_dir: Optional[str] = None
98
+ # Persistent output folder of the last run (if any) — recorded by
99
+ # _process_files so /api/reveal can open it without trusting any
100
+ # client-supplied path.
101
+ self.output_dir: Optional[str] = None
102
+ self.workspace: Optional[Path] = None
103
+ self.is_running = False
104
+ self.current = 0
105
+ self.total = 0
106
+ self.logs: list = []
107
+ self.cancelled = False
108
+ self.paused = False
109
+ self.last_seen = time.time()
110
+ self.scan_running = False
111
+ self.scan_current = 0
112
+ self.scan_total = 0
113
+ self.scan_error: Optional[str] = None
114
+ # ZIP download cache: output_version bumps once per completed run
115
+ # (outputs changed); zip_built_version records which version the
116
+ # on-disk optimized.zip reflects, so download_zip can skip a rebuild
117
+ # when nothing changed since the last archive.
118
+ self.output_version = 0
119
+ self.zip_built_version = -1
120
+ # Watch mode (auto-optimize): a per-session background task that
121
+ # polls a directory and compresses new/changed images as they
122
+ # appear. Independent of state.files/results/workspace — it writes
123
+ # straight into the user's chosen output_dir. Name has no leading
124
+ # underscore unlike most sibling fields because it's manipulated
125
+ # from endpoints and helpers, not just this class.
126
+ self.watch_running = False
127
+ self.watch_dir: Optional[str] = None
128
+ self.watch_output_dir: Optional[str] = None
129
+ self.watch_task: Optional[asyncio.Task] = None
130
+ self.watch_watcher: Optional[FolderWatcher] = None
131
+ self.watch_processed = 0
132
+ self.watch_errors = 0
133
+ self.watch_logs: list = []
134
+
135
+ def reset(self):
136
+ self.files = []
137
+ self.results = []
138
+ self.input_dir = None
139
+ self.output_dir = None
140
+ self.is_running = False
141
+ self.current = 0
142
+ self.total = 0
143
+ self.logs = []
144
+ self.cancelled = False
145
+ self.paused = False
146
+ self.scan_running = False
147
+ self.scan_current = 0
148
+ self.scan_total = 0
149
+ self.scan_error = None
150
+ self.output_version = 0
151
+ self.zip_built_version = -1
152
+
153
+ def new_workspace(self):
154
+ if self.workspace:
155
+ old = self.workspace
156
+ try:
157
+ # Don't delete the old workspace synchronously — another
158
+ # request (e.g. a download or image load in a different
159
+ # tab) may still be reading from it. Give in-flight
160
+ # requests a grace period instead of yanking the directory
161
+ # out from under them.
162
+ asyncio.get_running_loop()
163
+ asyncio.create_task(_delayed_rmtree(old))
164
+ except RuntimeError:
165
+ # No running event loop (e.g. the --dir CLI startup path,
166
+ # which runs before uvicorn starts) — nothing could be
167
+ # reading from it yet, safe to delete immediately.
168
+ shutil.rmtree(old, ignore_errors=True)
169
+ self.workspace = Path(tempfile.mkdtemp(prefix="imgopt_"))
170
+ return self.workspace
171
+
172
+
173
+ # Each browser session (identified by a cookie) gets its own AppState, so
174
+ # two different browsers/profiles — or two people on the same LAN if this
175
+ # were ever pointed at 0.0.0.0 — no longer share scan results, progress, or
176
+ # a workspace and can't clobber each other's in-flight work. Note the
177
+ # cookie is browser-wide, NOT per-tab: two tabs in the same browser still
178
+ # share one AppState, which is why the scan/optimize endpoints reject
179
+ # concurrent work with a 400 instead of silently swapping state.
180
+ SESSIONS: dict[str, AppState] = {}
181
+ SESSION_COOKIE = "imgopt_session"
182
+ SESSION_IDLE_TIMEOUT = 4 * 3600 # sweep sessions untouched for this long
183
+ SESSION_SWEEP_INTERVAL = 600
184
+
185
+ # Populated once by `--dir` at CLI startup (before any HTTP request exists,
186
+ # so there's no session yet to attach it to) and handed to whichever
187
+ # session is created first, so the browser that opens still sees the
188
+ # pre-scanned folder. Cleared after being consumed once.
189
+ _cli_prescan_state: Optional[AppState] = None
190
+
191
+
192
+ def get_session(request: Request) -> AppState:
193
+ global _cli_prescan_state
194
+ sid = request.cookies.get(SESSION_COOKIE)
195
+ st = SESSIONS.get(sid) if sid else None
196
+ if st is None:
197
+ sid = secrets.token_urlsafe(24)
198
+ st = _cli_prescan_state if _cli_prescan_state is not None else AppState()
199
+ _cli_prescan_state = None
200
+ SESSIONS[sid] = st
201
+ # Stashed for session_cookie_middleware below to pick up — a
202
+ # dependency mutating an injected Response object only takes effect
203
+ # if the route handler lets FastAPI build the response itself, but
204
+ # nearly every route here returns its own JSONResponse/HTMLResponse
205
+ # explicitly, which would silently discard that. Middleware runs on
206
+ # the actual outgoing response regardless, so it's reliable here.
207
+ request.state.new_session_id = sid
208
+ st.last_seen = time.time()
209
+ return st
210
+
211
+
212
+ async def _sweep_stale_sessions_once() -> None:
213
+ """One sweep pass: drop sessions idle past SESSION_IDLE_TIMEOUT. Split
214
+ out from _sweep_stale_sessions so tests can trigger a single pass
215
+ directly instead of waiting on the real interval."""
216
+ now = time.time()
217
+ stale = [sid for sid, st in SESSIONS.items() if now - st.last_seen > SESSION_IDLE_TIMEOUT]
218
+ for sid in stale:
219
+ st = SESSIONS.pop(sid, None)
220
+ if st is None:
221
+ continue
222
+ # A session can go stale while Watch Mode is still running — that's
223
+ # the normal "fire and forget" use case, not an edge case — so it
224
+ # must be cancelled here, not just dropped from SESSIONS. Without
225
+ # this, watch_task (created in watch_start) keeps polling forever:
226
+ # its closure holds a live reference to `st`, keeping the whole
227
+ # AppState — including the ever-growing watch_logs list — alive
228
+ # and running with no way for the user to reach it again (a
229
+ # reconnect gets a brand-new AppState, unaware the old task still
230
+ # exists). No-op if watch wasn't running.
231
+ # See test_stale_sweep_cancels_orphaned_watch_task.
232
+ await _stop_watch(st)
233
+ if st.workspace:
234
+ # Each stale workspace gets deleted off the event loop — a
235
+ # sweep that grabs several oversized sessions in one pass
236
+ # could otherwise freeze the server for the combined delete
237
+ # duration, right when a still-active session's progress poll
238
+ # is exactly the request we'd want not to stall.
239
+ await _async_rmtree(st.workspace)
240
+
241
+
242
+ async def _sweep_stale_sessions():
243
+ while True:
244
+ await asyncio.sleep(SESSION_SWEEP_INTERVAL)
245
+ await _sweep_stale_sessions_once()
246
+
247
+
248
+ optimizer: Optional[Optimizer] = None
249
+
250
+ # Generated fresh each time the process starts. Injected into the page on
251
+ # load and required (as a custom header) on every state-changing API call.
252
+ # This isn't about keeping a secret from the person using the app — it's
253
+ # about making sure a request actually came from this app's own page:
254
+ # adding a custom header forces the browser to send a CORS preflight for
255
+ # cross-origin requests, and since this server sends no CORS headers at
256
+ # all, that preflight always fails closed. A malicious page open in another
257
+ # tab has no way to read this token (same-origin policy) and so can never
258
+ # construct a request this server will accept.
259
+ APP_TOKEN = secrets.token_urlsafe(32)
260
+
261
+
262
+ async def require_token(x_app_token: str = Header(default="")):
263
+ if not secrets.compare_digest(x_app_token, APP_TOKEN):
264
+ raise HTTPException(status_code=403, detail="Missing or invalid app token")
265
+
266
+ RECENT_LIMIT = 8
267
+
268
+
269
+ def _config_dir() -> Path:
270
+ # A single, predictable location on every OS (like ~/.ssh, ~/.npm,
271
+ # ~/.docker) rather than following each platform's own convention
272
+ # (APPDATA on Windows, XDG_CONFIG_HOME on Linux/macOS) — easier to
273
+ # find and document with one path instead of three.
274
+ d = Path.home() / ".image-optimizer"
275
+ try:
276
+ d.mkdir(parents=True, exist_ok=True)
277
+ except Exception:
278
+ pass
279
+ return d
280
+
281
+
282
+ def _recent_file() -> Path:
283
+ return _config_dir() / "recent.json"
284
+
285
+
286
+ def _batch_state_dir() -> Path:
287
+ d = _config_dir() / "batches"
288
+ try:
289
+ d.mkdir(parents=True, exist_ok=True)
290
+ except OSError:
291
+ pass
292
+ return d
293
+
294
+
295
+ def _batch_id_for_output_dir(output_dir: str) -> str:
296
+ """Stable id for a batch, derived from its output_dir rather than the
297
+ browser session. Session ids are ephemeral — they're re-issued on every
298
+ server restart (see get_session), which is exactly when resume needs to
299
+ work — so keying storage by session would make a crash-restart batch
300
+ un-resumable. output_dir is what the resume flow already treats as a
301
+ batch's identity (start_optimization rejects a resume whose output_dir
302
+ doesn't match), and unlike a session it's stable across restarts and
303
+ naturally distinct between unrelated batches, so two tabs/processes
304
+ running different batches can no longer collide on one shared file."""
305
+ normalized = str(Path(output_dir).resolve())
306
+ return hashlib.sha256(normalized.encode("utf-8")).hexdigest()[:16]
307
+
308
+
309
+ def _batch_state_file(output_dir: str) -> Path:
310
+ return _batch_state_dir() / f"{_batch_id_for_output_dir(output_dir)}.json"
311
+
312
+
313
+ def _load_batch_state(output_dir: str) -> Optional[dict]:
314
+ """Load the batch persisted for this output_dir, if any.
315
+ Returns None if there's no such file or it's corrupt."""
316
+ try:
317
+ return json.loads(_batch_state_file(output_dir).read_text(encoding="utf-8"))
318
+ except (FileNotFoundError, json.JSONDecodeError, OSError):
319
+ return None
320
+
321
+
322
+ def _save_batch_state(bs: dict):
323
+ """Persist batch state to disk, scoped to its own output_dir. Called
324
+ after each file completes so a crash / server restart can pick up
325
+ where it left off, without touching any other batch's file."""
326
+ output_dir = bs.get("output_dir")
327
+ if not output_dir:
328
+ return # nothing to scope the file to — shouldn't happen in practice
329
+ try:
330
+ bs["updated_at"] = time.strftime("%Y-%m-%dT%H:%M:%S")
331
+ _batch_state_file(output_dir).write_text(
332
+ json.dumps(bs, indent=2, ensure_ascii=False), encoding="utf-8"
333
+ )
334
+ except OSError:
335
+ pass # best-effort — a write failure here mustn't crash the batch
336
+
337
+
338
+ def _clear_batch_state(output_dir: str):
339
+ """Remove one batch's state file — called when that batch completes
340
+ fully. Only ever touches the file for this specific output_dir, so an
341
+ unrelated batch finishing elsewhere can't wipe this one's resume data."""
342
+ try:
343
+ _batch_state_file(output_dir).unlink(missing_ok=True)
344
+ except OSError:
345
+ pass
346
+
347
+
348
+ def _list_unfinished_batch_states() -> list[dict]:
349
+ """Every persisted batch that still has pending/failed files, newest
350
+ first. Used to populate the resume banner without requiring the caller
351
+ to already know which output_dir to ask about."""
352
+ out = []
353
+ for f in _batch_state_dir().glob("*.json"):
354
+ try:
355
+ bs = json.loads(f.read_text(encoding="utf-8"))
356
+ except (json.JSONDecodeError, OSError):
357
+ continue
358
+ files = bs.get("files", [])
359
+ if any(item.get("status") in ("pending", "failed") for item in files):
360
+ out.append(bs)
361
+ out.sort(key=lambda bs: bs.get("updated_at", ""), reverse=True)
362
+ return out
363
+
364
+
365
+ def _skip_fingerprints_dir() -> Path:
366
+ d = _config_dir() / "skip_fingerprints"
367
+ try:
368
+ d.mkdir(parents=True, exist_ok=True)
369
+ except OSError:
370
+ pass
371
+ return d
372
+
373
+
374
+ def _skip_fingerprints_file(output_dir: str) -> Path:
375
+ # Reuses the same output_dir → stable id scheme as batch state (see
376
+ # _batch_id_for_output_dir) — same reasoning applies: output_dir is
377
+ # what identifies "this run's destination", stable across restarts,
378
+ # distinct between unrelated runs.
379
+ return _skip_fingerprints_dir() / f"{_batch_id_for_output_dir(output_dir)}.json"
380
+
381
+
382
+ def _load_skip_fingerprints(output_dir: str) -> dict:
383
+ """rel_path -> fingerprint of the settings that produced the current
384
+ file at that path, for one output_dir. Missing/corrupt file -> {} (an
385
+ empty map means "nothing recorded", which skip_existing treats as
386
+ unverifiable and recompresses rather than trusting a stale file blindly
387
+ — see the reuse check in _process_files)."""
388
+ try:
389
+ return json.loads(_skip_fingerprints_file(output_dir).read_text(encoding="utf-8"))
390
+ except (FileNotFoundError, json.JSONDecodeError, OSError):
391
+ return {}
392
+
393
+
394
+ def _save_skip_fingerprints(output_dir: str, data: dict):
395
+ try:
396
+ _skip_fingerprints_file(output_dir).write_text(json.dumps(data), encoding="utf-8")
397
+ except OSError:
398
+ pass # best-effort — a write failure here just means the next run recompresses instead of reusing
399
+
400
+
401
+ # Defaults for everything a config.json can override. CLI flags (where they
402
+ # exist) take priority over the config file, which takes priority over
403
+ # these. Keep this in sync with README's config.json documentation.
404
+ DEFAULT_CONFIG = {
405
+ "host": "127.0.0.1",
406
+ "port": 8090,
407
+ "concurrent_workers": 4, # how many images to compress at once (pngquant/oxipng/Pillow)
408
+ "thumbnail_workers": 4, # how many images to thumbnail at once during a scan
409
+ "workspace_cleanup_delay": 10.0, # seconds to wait before deleting a replaced workspace
410
+ "session_idle_timeout_hours": 4, # how long an inactive browser session is kept
411
+ }
412
+
413
+
414
+ def _config_file() -> Path:
415
+ return _config_dir() / "config.json"
416
+
417
+
418
+ def _load_app_config() -> dict:
419
+ cfg = dict(DEFAULT_CONFIG)
420
+ try:
421
+ raw = json.loads(_config_file().read_text(encoding="utf-8"))
422
+ except FileNotFoundError:
423
+ return cfg
424
+ except Exception as e:
425
+ # Startup diagnostics always go to stderr: with --source --json the
426
+ # stdout contract is "exactly one JSON object" (see _run_cli), and the
427
+ # config load runs before that report is produced.
428
+ print(f"[Warning] Ignoring unreadable config.json ({_config_file()}): {e}", file=sys.stderr)
429
+ return cfg
430
+
431
+ for key, value in raw.items():
432
+ if key not in cfg:
433
+ print(f"[Warning] Ignoring unknown config.json key: {key!r}", file=sys.stderr)
434
+ continue
435
+ cfg[key] = value
436
+
437
+ # Validate rather than trust blindly — a hand-edited config file with a
438
+ # typo'd value shouldn't crash startup or silently misbehave (e.g. a
439
+ # negative/zero worker count would make the scan/optimize queues never
440
+ # drain). Uses an explicit ValueError, NOT `assert`, because `python -O`
441
+ # strips assertions out entirely — running the app with `-O` would then
442
+ # silently accept e.g. ..."port": 99999} (out of valid port range) and
443
+ # bind to a garbage port, or accept a negative cleanup delay, defeating
444
+ # the whole point of the guard.
445
+ try:
446
+ cfg["port"] = int(cfg["port"])
447
+ if not (1 <= cfg["port"] <= 65535):
448
+ raise ValueError("port out of range 1-65535")
449
+ except Exception:
450
+ print(f"[Warning] Invalid config.json 'port' ({cfg['port']!r}), using default {DEFAULT_CONFIG['port']}", file=sys.stderr)
451
+ cfg["port"] = DEFAULT_CONFIG["port"]
452
+ try:
453
+ cfg["concurrent_workers"] = int(cfg["concurrent_workers"])
454
+ if cfg["concurrent_workers"] < 1:
455
+ raise ValueError("concurrent_workers must be >= 1")
456
+ except Exception:
457
+ print(
458
+ f"[Warning] Invalid config.json 'concurrent_workers' ({cfg['concurrent_workers']!r}), "
459
+ f"using default {DEFAULT_CONFIG['concurrent_workers']}",
460
+ file=sys.stderr,
461
+ )
462
+ cfg["concurrent_workers"] = DEFAULT_CONFIG["concurrent_workers"]
463
+ try:
464
+ cfg["thumbnail_workers"] = int(cfg["thumbnail_workers"])
465
+ if cfg["thumbnail_workers"] < 1:
466
+ raise ValueError("thumbnail_workers must be >= 1")
467
+ except Exception:
468
+ print(
469
+ f"[Warning] Invalid config.json 'thumbnail_workers' ({cfg['thumbnail_workers']!r}), "
470
+ f"using default {DEFAULT_CONFIG['thumbnail_workers']}",
471
+ file=sys.stderr,
472
+ )
473
+ cfg["thumbnail_workers"] = DEFAULT_CONFIG["thumbnail_workers"]
474
+ try:
475
+ cfg["workspace_cleanup_delay"] = float(cfg["workspace_cleanup_delay"])
476
+ if cfg["workspace_cleanup_delay"] < 0:
477
+ raise ValueError("workspace_cleanup_delay must be >= 0")
478
+ except Exception:
479
+ cfg["workspace_cleanup_delay"] = DEFAULT_CONFIG["workspace_cleanup_delay"]
480
+ try:
481
+ cfg["session_idle_timeout_hours"] = float(cfg["session_idle_timeout_hours"])
482
+ if cfg["session_idle_timeout_hours"] <= 0:
483
+ raise ValueError("session_idle_timeout_hours must be > 0")
484
+ except Exception:
485
+ cfg["session_idle_timeout_hours"] = DEFAULT_CONFIG["session_idle_timeout_hours"]
486
+
487
+ return cfg
488
+
489
+
490
+ def _load_recent() -> dict:
491
+ try:
492
+ data = json.loads(_recent_file().read_text(encoding="utf-8"))
493
+ data.setdefault("scan_dirs", [])
494
+ data.setdefault("output_dirs", [])
495
+ return data
496
+ except Exception:
497
+ return {"scan_dirs": [], "output_dirs": []}
498
+
499
+
500
+ def _save_recent(data: dict):
501
+ try:
502
+ _recent_file().write_text(json.dumps(data), encoding="utf-8")
503
+ except Exception:
504
+ pass # best-effort — a read-only config dir shouldn't break the app
505
+
506
+
507
+ def _push_recent(key: str, path: str):
508
+ if not path:
509
+ return
510
+ data = _load_recent()
511
+ lst = [p for p in data.get(key, []) if p != path]
512
+ lst.insert(0, path)
513
+ data[key] = lst[:RECENT_LIMIT]
514
+ _save_recent(data)
515
+
516
+
517
+ @asynccontextmanager
518
+ async def lifespan(app: FastAPI):
519
+ global optimizer
520
+ optimizer = Optimizer(max_concurrency=CONCURRENT_WORKERS)
521
+ tools = []
522
+ if optimizer.pngquant_path:
523
+ tools.append(f"pngquant: {optimizer.pngquant_path}")
524
+ if optimizer.oxipng_path:
525
+ tools.append(f"oxipng: {optimizer.oxipng_path}")
526
+ if optimizer.cjpeg_path:
527
+ tools.append(f"cjpeg: {optimizer.cjpeg_path}")
528
+ if tools:
529
+ print(f"[Startup] Detected: {', '.join(tools)}")
530
+ else:
531
+ print(
532
+ "[Startup] pngquant/oxipng/cjpeg/avifenc not found — WebP output still works. "
533
+ f"Run with automatic download (default) or place binaries in {binaries.binary_dir()}"
534
+ )
535
+ sweep_task = asyncio.create_task(_sweep_stale_sessions())
536
+ yield
537
+ sweep_task.cancel()
538
+ for st in SESSIONS.values():
539
+ if st.workspace:
540
+ try:
541
+ await _async_rmtree(st.workspace)
542
+ except Exception:
543
+ pass
544
+
545
+
546
+ app = FastAPI(title="Image Optimizer", lifespan=lifespan)
547
+
548
+
549
+ @app.middleware("http")
550
+ async def session_cookie_middleware(request: Request, call_next):
551
+ response = await call_next(request)
552
+ new_sid = getattr(request.state, "new_session_id", None)
553
+ if new_sid:
554
+ response.set_cookie(
555
+ SESSION_COOKIE, new_sid, httponly=True, samesite="lax", max_age=SESSION_IDLE_TIMEOUT
556
+ )
557
+ return response
558
+
559
+
560
+ def _gen_thumbnail(src: Path, dst: Path, max_size: int = 200):
561
+ try:
562
+ # Context manager so the source file handle is released even on the
563
+ # error path (matters on Windows, where a lingering handle can keep
564
+ # the user's file locked until GC gets around to it).
565
+ with Image.open(src) as img:
566
+ img.thumbnail((max_size, max_size), Image.Resampling.LANCZOS)
567
+ if img.mode in ("RGBA", "LA", "PA", "P"):
568
+ # Composite transparency onto white instead of a bare
569
+ # convert("RGB"), which renders transparent areas black.
570
+ # Also covers LA/PA, whose alpha made the JPEG save fail
571
+ # outright (no thumbnail at all).
572
+ rgba = img.convert("RGBA")
573
+ bg = Image.new("RGB", rgba.size, (255, 255, 255))
574
+ bg.paste(rgba, mask=rgba.getchannel("A"))
575
+ img = bg
576
+ elif img.mode != "RGB":
577
+ img = img.convert("RGB")
578
+ dst.parent.mkdir(parents=True, exist_ok=True)
579
+ img.save(dst, "JPEG", quality=70)
580
+ except Exception as e:
581
+ print(f"[Warning] Thumbnail failed for {src.name}: {e}")
582
+
583
+
584
+ # Display label for Pillow's `mode` string on the Compare page. Deliberately
585
+ # a friendly bits-per-pixel summary of the *decoded* representation, not the
586
+ # exact on-disk encoding (e.g. a low-bit-depth palette PNG still decodes to
587
+ # mode "P" here) — precise enough for "did this change color depth" at a
588
+ # glance without parsing each container format's own bit-depth field.
589
+ _MODE_LABELS = {
590
+ "1": "1-bit",
591
+ "L": "8-bit grayscale",
592
+ "LA": "16-bit grayscale+alpha",
593
+ "P": "8-bit indexed",
594
+ "PA": "16-bit indexed+alpha",
595
+ "RGB": "24-bit RGB",
596
+ "RGBA": "32-bit RGBA",
597
+ "CMYK": "32-bit CMYK",
598
+ "YCbCr": "24-bit YCbCr",
599
+ "I": "32-bit integer",
600
+ "I;16": "16-bit grayscale",
601
+ "F": "32-bit float",
602
+ }
603
+
604
+
605
+ def _get_image_info(path: Path) -> Optional[dict]:
606
+ """Width/height/bit-depth for the Compare page. Returns None (not a
607
+ dict with placeholder values) on any failure to open/decode — e.g. an
608
+ AVIF file if the installed Pillow build lacks AVIF support — so the
609
+ caller can render an explicit "unavailable" state instead of a blank or
610
+ misleading number. Same try/except-and-report shape as _gen_thumbnail
611
+ above, applied here for the same reason: a read failure must be visible,
612
+ not silently swallowed into a default.
613
+ """
614
+ try:
615
+ with Image.open(path) as img:
616
+ w, h = img.size
617
+ depth = _MODE_LABELS.get(img.mode, img.mode)
618
+ return {"width": w, "height": h, "depth": depth}
619
+ except Exception as e:
620
+ print(f"[Warning] Reading image info failed for {path.name}: {e}")
621
+ return None
622
+
623
+
624
+ # Starlette's FileResponse falls back to Python's `mimetypes` module when
625
+ # no media_type is given, which on Windows reads from the registry rather
626
+ # than a built-in table — .webp (and sometimes others) frequently isn't
627
+ # registered there, silently serving image/webp files as
628
+ # application/octet-stream instead. Serving these explicitly sidesteps
629
+ # that OS-dependent guesswork entirely. Caught by Windows CI, not visible
630
+ # on Linux where Python's built-in mimetypes table already has .webp.
631
+ _MEDIA_TYPES = {
632
+ ".png": "image/png",
633
+ ".jpg": "image/jpeg",
634
+ ".jpeg": "image/jpeg",
635
+ ".bmp": "image/bmp",
636
+ ".tif": "image/tiff",
637
+ ".tiff": "image/tiff",
638
+ ".webp": "image/webp",
639
+ ".avif": "image/avif",
640
+ }
641
+
642
+
643
+ def _media_type_for(path: Path) -> Optional[str]:
644
+ return _MEDIA_TYPES.get(path.suffix.lower())
645
+
646
+
647
+ def _fmt_size(b: int) -> str:
648
+ if b < 1024:
649
+ return f"{b} B"
650
+ if b < 1024 * 1024:
651
+ return f"{b / 1024:.1f} KB"
652
+ return f"{b / (1024 * 1024):.2f} MB"
653
+
654
+
655
+ # Strings for the standalone Compare page (see /api/preview below). This
656
+ # page is server-rendered and opened in its own tab/window, so it can't
657
+ # share index.html's client-side I18N dict or read its localStorage — the
658
+ # caller passes its current language as a ?lang= query param instead (see
659
+ # the previewUrl construction in index.html). Keep in step with
660
+ # index.html's I18N when adding a language; only "en"/"zh" exist today.
661
+ PREVIEW_I18N = {
662
+ "en": {
663
+ "not_found": "Not found",
664
+ "title_prefix": "Compare - ",
665
+ "saved": "saved {pct}%",
666
+ "side_by_side": "Side by Side",
667
+ "overlay": "Overlay",
668
+ "fit": "Fit",
669
+ "fit_title": "Scale images to fit the window",
670
+ "zoom100": "100%",
671
+ "zoom100_title": "Show actual pixels — the real test for whether text stays sharp",
672
+ "original_label": "Original ({size})",
673
+ "compressed_label": "Compressed ({size})",
674
+ "original": "Original",
675
+ "compressed": "Compressed",
676
+ "toggle_suffix": " \u2014 click image to toggle (or press space)",
677
+ "footer_overlay": "Click the image (or press space) to flip between original and compressed",
678
+ "footer_side": "Original (left) vs Compressed (right)",
679
+ "footer_slider": "Drag the handle to compare, original on the left and compressed on the right",
680
+ "zoom_hint": " (scroll to pan around at actual size)",
681
+ "info_unavailable": "info unavailable",
682
+ "slider": "Slider",
683
+ },
684
+ "zh": {
685
+ "not_found": "未找到",
686
+ "title_prefix": "对比 - ",
687
+ "saved": "节省 {pct}%",
688
+ "side_by_side": "并排对比",
689
+ "overlay": "叠加对比",
690
+ "fit": "适应窗口",
691
+ "fit_title": "缩放图片以适应窗口",
692
+ "zoom100": "100%",
693
+ "zoom100_title": "显示实际像素——检验文字是否保持清晰的真正标准",
694
+ "original_label": "原图({size})",
695
+ "compressed_label": "压缩后({size})",
696
+ "original": "原图",
697
+ "compressed": "压缩后",
698
+ "toggle_suffix": "\u2014点击图片切换(或按空格键)",
699
+ "footer_overlay": "点击图片(或按空格键)切换原图与压缩后效果",
700
+ "footer_side": "原图(左)对比压缩后(右)",
701
+ "footer_slider": "拖动把手对比,左侧原图,右侧压缩后",
702
+ "zoom_hint": "(可滚动查看实际尺寸下的细节)",
703
+ "info_unavailable": "信息不可用",
704
+ "slider": "滑动对比",
705
+ },
706
+ }
707
+
708
+
709
+ async def _run_worker_pool(
710
+ items: list,
711
+ process_item: Callable[[Any], Awaitable[None]],
712
+ *,
713
+ n_workers: Optional[int] = None,
714
+ cancel_check: Optional[Callable[[], bool]] = None,
715
+ pause_check: Optional[Callable[[], bool]] = None,
716
+ on_item_error: Optional[Callable[[Any, Exception], None]] = None,
717
+ on_item_done: Optional[Callable[[Any], None]] = None,
718
+ ):
719
+ """Shared queue + worker pool used by both the scan flow
720
+ (`_scan_and_thumbnail`) and the compression flow (`_process_files`).
721
+
722
+ What's shared here is exactly the part that was duplicated:
723
+ - pre-fill an asyncio.Queue with the work items
724
+ - spin up N workers, each draining the queue with get_nowait()
725
+ - await asyncio.gather() on the pool
726
+ - call `on_item_done(item)` once per processed item (success or
727
+ per-item exception) so a progress counter is bumped exactly once
728
+ — both scan and optimize had the same `finally: state.X += 1`
729
+ line before, so promoting it here. Cancelled-but-not-started
730
+ items do NOT call it (see the cancel note below).
731
+ - make sure an unhandled exception raised by `process_item` degrades
732
+ to `on_item_error(item, e)` and never propagates out of the worker
733
+ (an uncaught exception makes gather() return immediately while the
734
+ other workers keep running orphaned — see CHANGELOG "[Unreleased]"
735
+ and test_concurrency.test_one_file_raising_does_not_orphan_the_others
736
+ for the bug this guard prevents).
737
+
738
+ What is NOT shared, on purpose:
739
+ - how a result is stored: scan assigns into a preallocated list by
740
+ index (deterministic sorted order, regression-tested by
741
+ test_files_are_in_sorted_order_despite_concurrency); optimize
742
+ appends to state.results. Each side keeps its own storage logic
743
+ inside its `process_item` closure.
744
+ - cancel behavior: optimize drains the queue without starting new
745
+ work once cancelled; scan has no cancel path. Kept in `cancel_check`
746
+ so it's only checked when the caller opts in. A cancelled item is
747
+ drained without calling `on_item_done` — that matches the old
748
+ optimize behavior, where cancelled-but-not-started files did NOT
749
+ bump the progress counter, so `state.current < state.total`
750
+ after a cancel is the signal that the run was partial (see
751
+ test_cancel_stops_new_work_but_finishes_in_flight).
752
+
753
+ `n_workers` reads the module global `CONCURRENT_WORKERS` lazily at call
754
+ time rather than as a default argument: `main()` rebinds that global
755
+ from config.json/`--workers` after the module body has finished running,
756
+ so capturing it as a default would freeze it at the startup default of 4
757
+ and ignore the configured value.
758
+ """
759
+ if n_workers is None:
760
+ n_workers = CONCURRENT_WORKERS
761
+
762
+ queue: asyncio.Queue = asyncio.Queue()
763
+ for item in items:
764
+ queue.put_nowait(item)
765
+
766
+ async def worker():
767
+ while True:
768
+ # Cancel takes precedence over everything (including pause): a
769
+ # paused-then-cancelled run drains the queue and ends. We check
770
+ # it first so a worker stuck in the pause loop below still
771
+ # observes a cancel and exits. See test_cancel_during_pause_ends_run.
772
+ cancelled = cancel_check and cancel_check()
773
+ if cancelled:
774
+ # Drain one item without processing. A cancelled item
775
+ # intentionally does NOT call on_item_done() — the original
776
+ # optimize flow didn't bump the progress counter for
777
+ # cancelled items (only files that actually started
778
+ # processing counted toward state.current), and that
779
+ # distinction is how /api/progress reports "current < total"
780
+ # after a cancel. Bumping here would erase that signal.
781
+ # See test_cancel_stops_new_work_but_finishes_in_flight.
782
+ try:
783
+ queue.get_nowait()
784
+ except asyncio.QueueEmpty:
785
+ return
786
+ queue.task_done()
787
+ continue
788
+ # Soft pause (optimize only): stop SCHEDULING new items, but
789
+ # anything already in flight (past this gate on another worker)
790
+ # runs to completion — no subprocess kill, no signal handling.
791
+ # Sleep briefly rather than busy-spinning; resume latency is one
792
+ # sleep interval (~50ms). If the queue is already empty there's
793
+ # nothing held back, so the worker exits (prevents a deadlock
794
+ # where a paused run with no queued work never completes).
795
+ if pause_check and pause_check():
796
+ if queue.empty():
797
+ return
798
+ await asyncio.sleep(0.05)
799
+ continue
800
+ try:
801
+ item = queue.get_nowait()
802
+ except asyncio.QueueEmpty:
803
+ return
804
+ try:
805
+ await process_item(item)
806
+ except Exception as e:
807
+ # Any exception process_item doesn't already catch must be
808
+ # caught here, per-item — see the comment block above.
809
+ if on_item_error is not None:
810
+ on_item_error(item, e)
811
+ finally:
812
+ if on_item_done is not None:
813
+ on_item_done(item)
814
+ queue.task_done()
815
+ # Yield to the event loop after every item, not just ones whose
816
+ # process_item happens to await something. process_one's
817
+ # skip_existing reuse branch is pure sync I/O (stat/exists/
818
+ # copy2, no await at all) — without this, one worker can drain
819
+ # an entire skip-heavy queue in a single uninterrupted
820
+ # synchronous burst, starving any concurrently connecting SSE/
821
+ # poll client of a chance to ever observe state.current move.
822
+ # See test_yields_after_every_item_even_when_process_item_never_awaits.
823
+ await asyncio.sleep(0)
824
+
825
+ workers = [asyncio.create_task(worker()) for _ in range(max(1, n_workers))]
826
+ await asyncio.gather(*workers)
827
+
828
+
829
+ SCAN_EXTS = {".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".tif", ".webp"}
830
+
831
+
832
+ def _scan_images(directory: Path, recursive: bool = True) -> list:
833
+ # One directory walk with a case-folded suffix check, instead of one
834
+ # glob pass per extension×case pattern. Catches mixed-case names like
835
+ # "photo.Png" on case-sensitive filesystems (the old explicit
836
+ # upper/lower pattern list missed those), and includes .webp — the
837
+ # optimizer reads it like any other Pillow-supported input.
838
+ iter_method = directory.rglob if recursive else directory.glob
839
+ return sorted(p for p in iter_method("*") if p.is_file() and p.suffix.lower() in SCAN_EXTS)
840
+
841
+
842
+ @app.exception_handler(Exception)
843
+ async def global_exception_handler(request: Request, exc: Exception):
844
+ import traceback
845
+ tb = traceback.format_exc()
846
+ print(f"[ERROR] {request.method} {request.url.path}: {exc}")
847
+ print(tb)
848
+ return JSONResponse(
849
+ {
850
+ "error": "Internal server error",
851
+ "detail": str(exc),
852
+ "path": request.url.path,
853
+ "method": request.method,
854
+ },
855
+ status_code=500,
856
+ )
857
+
858
+
859
+ @app.get("/", response_class=HTMLResponse)
860
+ async def index(state: AppState = Depends(get_session)):
861
+ html = (BASE_DIR / "templates" / "index.html").read_text(encoding="utf-8")
862
+ token_script = f'<script>window.APP_TOKEN = "{APP_TOKEN}";</script>'
863
+ html = html.replace("</head>", f"{token_script}\n</head>", 1)
864
+ return HTMLResponse(html)
865
+
866
+
867
+ @app.get("/api/health")
868
+ async def health():
869
+ if optimizer is None:
870
+ return JSONResponse({"error": "Optimizer not initialized"}, status_code=503)
871
+ # Re-detect every health check so that placing pngquant/oxipng in the
872
+ # bin/ directory (or PATH) after startup is reflected on the next page
873
+ # refresh — no restart needed. Detection shells out to `where`/`which`,
874
+ # which is blocking I/O — run it off the event loop so a health check
875
+ # never stalls other sessions' in-flight requests.
876
+ await asyncio.to_thread(optimizer._detect_binaries)
877
+ return JSONResponse({
878
+ "pngquant": optimizer.pngquant_path is not None,
879
+ "oxipng": optimizer.oxipng_path is not None,
880
+ "cjpeg": optimizer.cjpeg_path is not None,
881
+ "avifenc": optimizer.avifenc_path is not None,
882
+ "pngquant_path": str(optimizer.pngquant_path) if optimizer.pngquant_path else None,
883
+ "oxipng_path": str(optimizer.oxipng_path) if optimizer.oxipng_path else None,
884
+ "cjpeg_path": str(optimizer.cjpeg_path) if optimizer.cjpeg_path else None,
885
+ "avifenc_path": str(optimizer.avifenc_path) if optimizer.avifenc_path else None,
886
+ })
887
+
888
+
889
+ async def _scan_and_thumbnail(state: AppState, directory: Path, recursive: bool):
890
+ ws = state.workspace
891
+ try:
892
+ # `asyncio.get_event_loop()` inside a coroutine is the deprecated way
893
+ # of grabbing the loop — on Python 3.10+ `get_running_loop()` is
894
+ # the explicit counterpart, and is always safe here because we're in
895
+ # an async context. (See also upload_files/browse_folder below,
896
+ # where `asyncio.to_thread()` is the natural fit instead of going
897
+ # through an explicit loop reference.)
898
+ loop = asyncio.get_running_loop()
899
+ images = await loop.run_in_executor(None, _scan_images, directory, recursive)
900
+ except Exception as e:
901
+ state.scan_error = str(e)
902
+ state.scan_running = False
903
+ return
904
+
905
+ state.scan_total = len(images)
906
+ files: list = [None] * len(images) # preallocated so results land in a
907
+ # stable, deterministic order (matching the sorted scan order) even
908
+ # though workers finish in whatever order thumbnailing completes.
909
+
910
+ async def process_item(item):
911
+ idx, img_path = item
912
+ rel = str(img_path.relative_to(directory))
913
+ thumb_rel = f"thumb/{idx}_{img_path.stem}.jpg"
914
+ thumb_path = ws / thumb_rel
915
+ if not thumb_path.exists():
916
+ await asyncio.to_thread(_gen_thumbnail, img_path, thumb_path)
917
+ st = img_path.stat()
918
+ files[idx] = {
919
+ "id": str(idx),
920
+ "name": rel,
921
+ "path": str(img_path),
922
+ "size": st.st_size,
923
+ # Powers the Files-grid Sort dropdown: mtime = last modified,
924
+ # ctime = creation time on Windows (metadata-change time on
925
+ # POSIX, close enough for "newest first" ordering there).
926
+ "mtime": st.st_mtime,
927
+ "ctime": st.st_ctime,
928
+ "thumbnail": f"/api/thumb/{ws.name}/{thumb_rel}",
929
+ }
930
+
931
+ def on_item_error(item, e):
932
+ # One unreadable/corrupt file shouldn't stop the rest of the scan —
933
+ # same reasoning as the optimize worker pool.
934
+ idx, img_path = item
935
+ files[idx] = {
936
+ "id": str(idx),
937
+ "name": str(img_path),
938
+ "path": str(img_path),
939
+ "size": 0,
940
+ "mtime": 0,
941
+ "ctime": 0,
942
+ "thumbnail": "",
943
+ "error": str(e),
944
+ }
945
+
946
+ def on_item_done(_item):
947
+ state.scan_current += 1
948
+
949
+ await _run_worker_pool(
950
+ [(idx, img_path) for idx, img_path in enumerate(images)],
951
+ process_item,
952
+ n_workers=THUMBNAIL_WORKERS,
953
+ on_item_error=on_item_error,
954
+ on_item_done=on_item_done,
955
+ )
956
+
957
+ state.files = [f for f in files if f is not None]
958
+ state.total = len(state.files)
959
+ state.scan_running = False
960
+ _push_recent("scan_dirs", str(directory.resolve()))
961
+
962
+
963
+ async def _backfill_resume_thumbnails(state: "AppState", files: list):
964
+ """Generate thumbnails for files reconstructed on resume, concurrently
965
+ with the compression task the resume branch of start_optimization
966
+ already kicked off.
967
+
968
+ Deliberately NOT a call into _scan_and_thumbnail: that walks the whole
969
+ directory fresh and overwrites state.files/state.total at the end,
970
+ which would race with the compression task mutating state.total/
971
+ state.current/state.results at the same time — same class of bug as
972
+ the worker-pool/session-leak issues this project has already been bit
973
+ by. This only ever writes each file dict's own "thumbnail" key, on a
974
+ *fixed* list (the one resume already rebuilt) — it never touches
975
+ state.total or the list's membership/order, so there's nothing here
976
+ for the compression task (which writes "status"/state.results, not
977
+ "thumbnail") to race against.
978
+ """
979
+ ws = state.workspace
980
+ if ws is None or not files:
981
+ return
982
+
983
+ async def process_item(item):
984
+ idx, f = item
985
+ img_path = Path(f["path"])
986
+ if not img_path.exists():
987
+ return
988
+ thumb_rel = f"thumb/resume_{idx}_{img_path.stem}.jpg"
989
+ thumb_path = ws / thumb_rel
990
+ if not thumb_path.exists():
991
+ await asyncio.to_thread(_gen_thumbnail, img_path, thumb_path)
992
+ f["thumbnail"] = f"/api/thumb/{ws.name}/{thumb_rel}"
993
+
994
+ def on_item_error(item, e):
995
+ # Leave thumbnail as "" — same graceful degradation as a normal
996
+ # scan's on_item_error. Don't fail the whole backfill over one
997
+ # unreadable file; compression will report its own error for it
998
+ # independently if it's still pending.
999
+ pass
1000
+
1001
+ await _run_worker_pool(
1002
+ list(enumerate(files)),
1003
+ process_item,
1004
+ n_workers=THUMBNAIL_WORKERS,
1005
+ cancel_check=lambda: state.cancelled,
1006
+ on_item_error=on_item_error,
1007
+ )
1008
+
1009
+
1010
+ @app.post("/api/scan")
1011
+ async def scan_directory(data: ScanRequest, state: AppState = Depends(get_session), _auth: None = Depends(require_token)):
1012
+ if state.is_running:
1013
+ return JSONResponse({"error": "Optimization in progress, please wait"}, status_code=400)
1014
+ if state.scan_running:
1015
+ return JSONResponse({"error": "A scan is already in progress, please wait"}, status_code=400)
1016
+ directory = Path(data.directory)
1017
+ if not directory.exists() or not directory.is_dir():
1018
+ return JSONResponse({"error": "Directory does not exist"}, status_code=400)
1019
+
1020
+ state.reset()
1021
+ state.input_dir = str(directory.resolve())
1022
+ state.new_workspace()
1023
+ state.scan_running = True
1024
+ state.scan_current = 0
1025
+ state.scan_total = 0
1026
+
1027
+ asyncio.create_task(_scan_and_thumbnail(state, directory, data.recursive))
1028
+ return JSONResponse({"scanning": True})
1029
+
1030
+
1031
+ @app.get("/api/scan-progress")
1032
+ async def get_scan_progress(state: AppState = Depends(get_session)):
1033
+ return JSONResponse({
1034
+ "running": state.scan_running,
1035
+ "current": state.scan_current,
1036
+ "total": state.scan_total,
1037
+ "error": state.scan_error,
1038
+ "files": state.files if not state.scan_running else [],
1039
+ })
1040
+
1041
+
1042
+ @app.post("/api/upload")
1043
+ async def upload_files(files: List[UploadFile] = File(...), state: AppState = Depends(get_session), _auth: None = Depends(require_token)):
1044
+ if state.is_running:
1045
+ return JSONResponse({"error": "Optimization in progress, please wait"}, status_code=400)
1046
+ # Mirror the /api/scan guard: scanning runs in a fire-and-forget
1047
+ # background task writing thumbnails into state.workspace. Replacing
1048
+ # the workspace now would queue a _delayed_rmtree on it while those
1049
+ # workers are still writing — picture a worker finishing its
1050
+ # thumbnail write to a path in a directory the OS is about to nuke,
1051
+ # or a mid-scan tab being silently replaced because the user dropped
1052
+ # new files in another. Reject and let the in-flight scan finish.
1053
+ if state.scan_running:
1054
+ return JSONResponse({"error": "A scan is already in progress, please wait"}, status_code=400)
1055
+ state.reset()
1056
+ ws = state.new_workspace()
1057
+ upload_dir = ws / "uploads"
1058
+ upload_dir.mkdir(parents=True, exist_ok=True)
1059
+
1060
+ result_files = []
1061
+ for idx, f in enumerate(files):
1062
+ if not f.filename:
1063
+ continue
1064
+ # Path(...).name strips any directory components a non-browser
1065
+ # client could smuggle into the filename (browsers only ever send
1066
+ # a basename). The sanitized name must be used for BOTH the stored
1067
+ # file and the reported "name" field — file_info["name"] is later
1068
+ # joined onto the output directory in _process_files, so a raw
1069
+ # "../"-carrying filename would write outside the workspace.
1070
+ name = Path(f.filename.replace("\\", "/")).name
1071
+ if not name:
1072
+ continue
1073
+ unique_name = f"{int(time.time())}_{idx}_{name}"
1074
+ file_path = upload_dir / unique_name
1075
+ # Stream to disk in 1 MiB chunks instead of buffering each whole
1076
+ # file in memory — a batch of large images would otherwise spike
1077
+ # memory by the combined upload size.
1078
+ size = 0
1079
+ with open(file_path, "wb") as out:
1080
+ while chunk := await f.read(1024 * 1024):
1081
+ out.write(chunk)
1082
+ size += len(chunk)
1083
+
1084
+ thumb_rel = f"thumb/upload_{idx}_{name}.jpg"
1085
+ thumb_path = ws / thumb_rel
1086
+ await asyncio.to_thread(_gen_thumbnail, file_path, thumb_path)
1087
+
1088
+ st = file_path.stat()
1089
+ result_files.append({
1090
+ "id": str(idx),
1091
+ "name": name,
1092
+ "path": str(file_path),
1093
+ "size": size,
1094
+ # Same fields as the scan flow (see process_item above) so the
1095
+ # Files-grid Sort dropdown works for uploads too.
1096
+ "mtime": st.st_mtime,
1097
+ "ctime": st.st_ctime,
1098
+ "thumbnail": f"/api/thumb/{state.workspace.name}/{thumb_rel}",
1099
+ })
1100
+
1101
+ state.files = result_files
1102
+ state.total = len(result_files)
1103
+ return JSONResponse({"files": result_files, "count": len(result_files)})
1104
+
1105
+
1106
+ @app.get("/api/thumb/{ws_name}/{thumb_rel:path}")
1107
+ async def get_thumbnail(ws_name: str, thumb_rel: str, state: AppState = Depends(get_session)):
1108
+ if state.workspace and state.workspace.name == ws_name:
1109
+ p = (state.workspace / thumb_rel).resolve()
1110
+ base = str(state.workspace.resolve())
1111
+ if p.exists() and (str(p) == base or str(p).startswith(base + os.sep)):
1112
+ return FileResponse(str(p), media_type="image/jpeg")
1113
+ return Response(status_code=404)
1114
+
1115
+
1116
+ @app.post("/api/optimize")
1117
+ async def start_optimization(data: OptimizeRequest, state: AppState = Depends(get_session), _auth: None = Depends(require_token)):
1118
+ if state.is_running:
1119
+ return JSONResponse({"error": "Optimization in progress, please wait"}, status_code=400)
1120
+
1121
+ err = _validate_optimize_settings(
1122
+ data.quality, data.output_format, data.compression_mode, data.max_width, data.protected_colors,
1123
+ )
1124
+ if err:
1125
+ return JSONResponse({"error": err}, status_code=400)
1126
+
1127
+ if state.watch_running:
1128
+ return JSONResponse({"error": "Watch mode is running, stop it first"}, status_code=400)
1129
+
1130
+ # --- Resume flow ---
1131
+ # When resume=True, reconstruct state from batch_state.json. The server
1132
+ # may have restarted, so state.files is empty — we rebuild it from the
1133
+ # persisted batch state and only process files that weren't completed.
1134
+ batch_state = None
1135
+ previous_results = []
1136
+ if data.resume:
1137
+ if not data.output_dir:
1138
+ return JSONResponse(
1139
+ {"error": "Resume requires output_dir to identify which batch to resume"},
1140
+ status_code=400,
1141
+ )
1142
+ # Batch state is stored per output_dir (see _batch_state_file), so
1143
+ # this already only ever loads *this* batch — no separate mismatch
1144
+ # check needed, and no risk of picking up an unrelated batch that
1145
+ # happens to be saved for a different output_dir.
1146
+ bs = _load_batch_state(data.output_dir)
1147
+ if bs is None:
1148
+ return JSONResponse(
1149
+ {"error": "No resumable batch state found"},
1150
+ status_code=400,
1151
+ )
1152
+ # Reconstruct state.files from batch_state (server may have restarted)
1153
+ rebuilt = []
1154
+ for f in bs.get("files", []):
1155
+ p = Path(f["path"])
1156
+ if not p.exists():
1157
+ continue
1158
+ try:
1159
+ st = p.stat()
1160
+ mtime, ctime = st.st_mtime, st.st_ctime
1161
+ except OSError:
1162
+ mtime = ctime = 0
1163
+ rebuilt.append({
1164
+ "id": f.get("id", secrets.token_urlsafe(8)), "name": f["name"], "path": f["path"],
1165
+ "size": f.get("size", 0), "mtime": mtime, "ctime": ctime, "thumbnail": "",
1166
+ })
1167
+ state.files = rebuilt
1168
+ if not state.files:
1169
+ return JSONResponse(
1170
+ {"error": "Source files no longer available for resume"},
1171
+ status_code=400,
1172
+ )
1173
+ # Filter to pending/failed only
1174
+ pending_paths = {
1175
+ f["path"] for f in bs.get("files", [])
1176
+ if f["status"] in ("pending", "failed")
1177
+ }
1178
+ files_to_process = [
1179
+ f for f in state.files if f["path"] in pending_paths
1180
+ ]
1181
+ if not files_to_process:
1182
+ return JSONResponse(
1183
+ {"error": "No pending files to resume"},
1184
+ status_code=400,
1185
+ )
1186
+ # Restore previous results for the UI (compare, progress display)
1187
+ previous_results = bs.get("results", [])
1188
+ # input_dir was persisted at batch-creation time (see below) but
1189
+ # never read back out here — state.input_dir stayed None through
1190
+ # every resume, so /api/state kept reporting no source folder even
1191
+ # though the batch clearly has one. Restore it alongside results.
1192
+ state.input_dir = bs.get("input_dir", "")
1193
+ batch_state = bs
1194
+ # Create a workspace for this session (the old one is gone if the
1195
+ # server restarted — _process_files needs one for its output dir).
1196
+ if state.workspace is None:
1197
+ state.new_workspace()
1198
+ # Skip the normal file selection — resume uses its own filtered list
1199
+ # (fall through to the validation/override checks below with
1200
+ # files_to_process already set)
1201
+ else:
1202
+ files_to_process = state.files
1203
+ if data.file_ids is not None:
1204
+ ids = set(data.file_ids)
1205
+ files_to_process = [f for f in state.files if f["id"] in ids]
1206
+
1207
+ if not files_to_process:
1208
+ return JSONResponse({"error": "No files to process"}, status_code=400)
1209
+
1210
+ if data.output_dir:
1211
+ _push_recent("output_dirs", str(Path(data.output_dir).resolve()))
1212
+
1213
+ # Validate per-file overrides before mutating any state — a bad override
1214
+ # must fail the request loudly, not half-start a run. See
1215
+ # _validate_overrides for the field-value/unknown-key/resize_only rules.
1216
+ selected_ids = {f["id"] for f in files_to_process}
1217
+ ov_err = _validate_overrides(data.overrides, selected_ids, data.compression_mode, data.max_width, data.output_format)
1218
+ if ov_err:
1219
+ return JSONResponse({"error": ov_err}, status_code=400)
1220
+
1221
+ state.is_running = True
1222
+ state.current = 0
1223
+ state.total = len(files_to_process)
1224
+ state.logs = []
1225
+ state.cancelled = False
1226
+ state.paused = False
1227
+ if data.resume:
1228
+ # Restore previous results from the batch so the UI shows the full
1229
+ # picture (earlier successes + new ones as they complete).
1230
+ state.results = list(previous_results)
1231
+ # Thumbnails were never regenerated for the rebuilt file list (see
1232
+ # the resume branch above) — backfill them concurrently with the
1233
+ # compression task about to be kicked off below, rather than
1234
+ # blocking this response on it or leaving the grid empty for the
1235
+ # whole run.
1236
+ asyncio.create_task(_backfill_resume_thumbnails(state, state.files))
1237
+ elif data.retry:
1238
+ # Retry re-runs only the previously-failed files. Keep every result
1239
+ # that isn't being retried (the earlier successes and their outputs
1240
+ # on disk stay intact) and drop just the stale entries for the ids
1241
+ # about to be re-run, so they don't appear twice once the fresh
1242
+ # results are appended.
1243
+ retry_ids = {f["id"] for f in files_to_process}
1244
+ state.results = [r for r in state.results if r.get("id") not in retry_ids]
1245
+ else:
1246
+ state.results = []
1247
+
1248
+ # Create batch state for normal runs with a persistent output_dir —
1249
+ # this is what enables resume after a crash / server restart. Runs
1250
+ # without output_dir use a temp workspace that disappears anyway, so
1251
+ # there's nothing to resume into.
1252
+ if not data.resume and data.output_dir:
1253
+ batch_state = {
1254
+ "session_id": secrets.token_urlsafe(12),
1255
+ "input_dir": str(Path(state.files[0]["path"]).parent) if state.files else "",
1256
+ "output_dir": data.output_dir,
1257
+ "output_format": data.output_format,
1258
+ "quality": data.quality,
1259
+ "compression_mode": data.compression_mode,
1260
+ "files": [
1261
+ {"id": f["id"], "path": f["path"], "name": f["name"], "size": f.get("size", 0), "status": "pending"}
1262
+ for f in files_to_process
1263
+ ],
1264
+ "results": [],
1265
+ "created_at": time.strftime("%Y-%m-%dT%H:%M:%S"),
1266
+ "updated_at": time.strftime("%Y-%m-%dT%H:%M:%S"),
1267
+ }
1268
+ _save_batch_state(batch_state)
1269
+
1270
+ # Surface degraded capability up front instead of only as a per-file
1271
+ # log line: PNG+standard without pngquant still runs, but silently
1272
+ # downgrades to lossless-only compression — the user should know why
1273
+ # their files barely shrank. JPEG without cjpeg fails outright per-file,
1274
+ # so warn before any work starts. available_modes() is the source of
1275
+ # truth.
1276
+ warning = None
1277
+ if optimizer is not None and (data.output_format, data.compression_mode) not in optimizer.available_modes():
1278
+ if data.output_format in ("jpg", "jpeg"):
1279
+ warning = (
1280
+ "cjpeg (mozjpeg) not found — JPEG output isn't possible. Place cjpeg in the "
1281
+ "bin/ directory (or PATH) to compress JPEGs while keeping the JPEG format."
1282
+ )
1283
+ else:
1284
+ warning = (
1285
+ "pngquant not found — Standard mode PNG output falls back to lossless-only "
1286
+ "compression (larger files). Place pngquant in the bin/ directory for full compression."
1287
+ )
1288
+ state.logs.append(f"[Warning] {warning}")
1289
+
1290
+ asyncio.create_task(
1291
+ _process_files(
1292
+ state,
1293
+ files_to_process,
1294
+ data.quality,
1295
+ data.max_width,
1296
+ data.output_format,
1297
+ data.output_dir,
1298
+ data.compression_mode,
1299
+ data.protected_colors,
1300
+ data.dithering,
1301
+ retry=data.retry,
1302
+ skip_existing=data.skip_existing,
1303
+ keep_exif=data.keep_exif,
1304
+ overrides=data.overrides,
1305
+ batch_state=batch_state,
1306
+ )
1307
+ )
1308
+
1309
+ return JSONResponse({"ok": True, "total": len(files_to_process), "warning": warning})
1310
+
1311
+
1312
+ CONCURRENT_WORKERS = 4 # default; overridden by main() from config.json / --workers
1313
+ # Compression concurrency knob (alias of CONCURRENT_WORKERS for readability at
1314
+ # the call site). Kept as the same name the tests monkeypatch
1315
+ # (CONCURRENT_WORKERS) so the existing pause/concurrency tests keep working
1316
+ # when they force a single compress worker.
1317
+ # THUMBNAIL_WORKERS is the independent scan-thumbnail concurrency knob —
1318
+ # splitting the two lets a scan that's I/O-bound on thumbnail generation not
1319
+ # starve (or be starved by) a concurrent compression run in another session,
1320
+ # and lets each be tuned to the machine.
1321
+ THUMBNAIL_WORKERS = 4 # default; overridden by main() from config.json / --thumbnail-workers
1322
+
1323
+ # Fields a per-file override may set. Fixed list so the request shape can't
1324
+ # drift between frontend and backend. Unknown fields in an override are
1325
+ # rejected with 400 rather than silently ignored — a typo'd "qualitiy" must
1326
+ # fail loudly, not silently do nothing.
1327
+ OVERRIDEABLE_FIELDS = (
1328
+ "quality", "compression_mode", "max_width", "dithering",
1329
+ "protected_colors", "keep_exif", "output_format",
1330
+ )
1331
+
1332
+
1333
+ def _validate_optimize_settings(
1334
+ quality: str, output_format: str, compression_mode: str, max_width: int,
1335
+ protected_colors: list,
1336
+ ) -> Optional[str]:
1337
+ """The top-level (non-per-file-override) compression settings shared by
1338
+ every entry point that can start a run: /api/optimize, /api/preview-optimize,
1339
+ and watch mode start. Returns an error string on the first problem, or
1340
+ None if everything is valid.
1341
+
1342
+ This used to be ~15 lines duplicated near-verbatim at each of those 3
1343
+ call sites (each with its own copy of the same 5 checks) — one already
1344
+ drifted to a slightly different wording for the same resize_only/
1345
+ max_width rule. Consolidated here so a 4th entry point (CLI mode) gets
1346
+ the same validation for free instead of a 4th slightly-different copy,
1347
+ and so the next new check only needs to be added once.
1348
+ """
1349
+ if compression_mode not in ("standard", "lossless", "resize_only", "screenshot"):
1350
+ return "Invalid compression_mode"
1351
+ if compression_mode == "screenshot" and output_format != "png":
1352
+ return "Screenshot mode is PNG-only (it's a tuned pngquant pass, not a general codec setting)"
1353
+ if quality not in ("high", "medium", "low"):
1354
+ return f"Invalid quality: {quality!r}. Supported: 'high', 'medium', 'low'."
1355
+ if output_format not in ("png", "webp", "jpg", "avif"):
1356
+ return f"Unsupported output_format: {output_format!r}. Supported: 'png', 'webp', 'jpg', 'avif'."
1357
+ if compression_mode == "resize_only" and max_width <= 0:
1358
+ return "Resize Only mode requires Max Width (max_width must be > 0)"
1359
+ bad_colors = [c for c in protected_colors if not HEX_COLOR_RE.match(c.strip())]
1360
+ if bad_colors:
1361
+ return f"Invalid color(s) in Protect Colors: {', '.join(bad_colors)}. Use hex format like #2ecc71."
1362
+ return None
1363
+
1364
+
1365
+ def _validate_overrides(
1366
+ overrides: dict, selected_ids: set, top_mode: str, top_width: int, top_format: str
1367
+ ) -> Optional[str]:
1368
+ """Validate every per-file override entry. Returns an error string on the
1369
+ first problem, or None if all entries are well-formed.
1370
+
1371
+ Field-value checks (enum/colors/unknown-keys) run for EVERY entry, even
1372
+ ids not in the selection — a typo in an override for a deselected file is
1373
+ still a typo worth reporting. The resize_only+max_width and
1374
+ screenshot+PNG-only cross-checks only run for selected ids: an override
1375
+ on an unselected file has no effect, so complaining about it would be a
1376
+ false positive."""
1377
+ for fid, ov in overrides.items():
1378
+ if not isinstance(ov, dict):
1379
+ return f"Override for file {fid!r} must be an object"
1380
+ bad_keys = [k for k in ov if k not in OVERRIDEABLE_FIELDS]
1381
+ if bad_keys:
1382
+ return (f"Unknown override field(s) for file {fid!r}: {bad_keys}. "
1383
+ f"Supported: {list(OVERRIDEABLE_FIELDS)}")
1384
+ if "quality" in ov and ov["quality"] not in ("high", "medium", "low"):
1385
+ return f"Invalid quality in override for file {fid!r}: {ov['quality']!r}"
1386
+ if "compression_mode" in ov and ov["compression_mode"] not in ("standard", "lossless", "resize_only", "screenshot"):
1387
+ return f"Invalid compression_mode in override for file {fid!r}: {ov['compression_mode']!r}"
1388
+ if "output_format" in ov and ov["output_format"] not in ("png", "webp", "jpg", "avif"):
1389
+ return f"Invalid output_format in override for file {fid!r}: {ov['output_format']!r}"
1390
+ if "max_width" in ov and (not isinstance(ov["max_width"], int) or isinstance(ov["max_width"], bool) or ov["max_width"] < 0):
1391
+ return f"Invalid max_width in override for file {fid!r}: {ov['max_width']!r}"
1392
+ if "dithering" in ov and not isinstance(ov["dithering"], bool):
1393
+ return f"Invalid dithering in override for file {fid!r} (must be bool)"
1394
+ if "keep_exif" in ov and not isinstance(ov["keep_exif"], bool):
1395
+ return f"Invalid keep_exif in override for file {fid!r} (must be bool)"
1396
+ if "protected_colors" in ov:
1397
+ bc = [c for c in ov["protected_colors"] if not HEX_COLOR_RE.match(str(c).strip())]
1398
+ if bc:
1399
+ return f"Invalid color(s) in override for file {fid!r}: {', '.join(bc)}"
1400
+ # resize_only needs a max_width, and screenshot is PNG-only — check
1401
+ # the effective combination, but only for files actually being
1402
+ # processed.
1403
+ if fid in selected_ids:
1404
+ eff_mode = ov.get("compression_mode", top_mode)
1405
+ eff_width = ov.get("max_width", top_width)
1406
+ eff_format = ov.get("output_format", top_format)
1407
+ if eff_mode == "resize_only" and eff_width <= 0:
1408
+ return f"Resize Only mode requires Max Width (override for file {fid!r})"
1409
+ if eff_mode == "screenshot" and eff_format != "png":
1410
+ return f"Screenshot mode is PNG-only (override for file {fid!r})"
1411
+ return None
1412
+
1413
+
1414
+ def _resolve_collision_free_output_paths(
1415
+ items: list[tuple[str, str, str]], output_dir: Path,
1416
+ reserved_names: Optional[set[str]] = None,
1417
+ ) -> dict[str, Optional[Path]]:
1418
+ """Pre-assign an output path per item so name collisions are resolved
1419
+ deterministically: "photo.png" and "photo.jpg" both map to "photo.png"
1420
+ after the suffix swap and would silently overwrite each other if
1421
+ processed concurrently (last one to finish wins, both reported as
1422
+ successes). First occurrence keeps the plain name; later collisions get
1423
+ a numbered stem ("photo_2.png"). Keys are case-folded because Windows/
1424
+ macOS filesystems collide case-insensitively.
1425
+
1426
+ `items` is a list of (id, relative_name, effective_output_format)
1427
+ tuples — deliberately a plain tuple, not the web batch handler's
1428
+ file_info/overrides dict shape, so this same function is usable by any
1429
+ caller (web batch, CLI) without adapting to that shape first.
1430
+
1431
+ `reserved_names` seeds used_names with output names a *previous* call
1432
+ already claimed against this same output_dir (already-completed results
1433
+ kept in state.results across a resume or retry — see _process_files).
1434
+ Without this, each call starts with an empty used_names and only sees
1435
+ the items in front of it, so a name that's already spoken for by a
1436
+ result restored from before a server restart (resume) or a completed
1437
+ result being kept around (retry) doesn't block a *new* item from being
1438
+ assigned that same name. On resume specifically that produced two
1439
+ state.results entries with the same output_name — one pointing at the
1440
+ stale pre-restart file (via final_output_path), one at the freshly
1441
+ written workspace file — and _resolve_result_file's workspace-first
1442
+ check then silently served the new file's bytes for the old result's
1443
+ compare/preview link. Expected pre-lowercased (matching the
1444
+ case-folded strings used_names already stores) so this function can
1445
+ stay a simple string-set union without extra casing logic.
1446
+
1447
+ A None value in the returned dict marks a name whose resolved path
1448
+ escapes output_dir (should be impossible after the caller's own
1449
+ sanitization — this is defense in depth, not the primary check) and
1450
+ must be turned into a per-item failure by the caller.
1451
+ """
1452
+ base_resolved = str(output_dir.resolve())
1453
+ out_paths: dict[str, Optional[Path]] = {}
1454
+ used_names: set[str] = set(reserved_names or ())
1455
+ for item_id, name, eff_fmt in items:
1456
+ base = (output_dir / name).with_suffix(f".{eff_fmt}")
1457
+ candidate = base
1458
+ n = 2
1459
+ while str(candidate).lower() in used_names:
1460
+ candidate = base.with_name(f"{base.stem}_{n}{base.suffix}")
1461
+ n += 1
1462
+ used_names.add(str(candidate).lower())
1463
+ resolved = str(candidate.resolve())
1464
+ inside = resolved == base_resolved or resolved.startswith(base_resolved + os.sep)
1465
+ out_paths[item_id] = candidate if inside else None
1466
+ return out_paths
1467
+
1468
+
1469
+ async def _process_files(
1470
+ state: AppState,
1471
+ files: list,
1472
+ quality: str,
1473
+ max_width: int,
1474
+ output_format: str,
1475
+ output_dir: str = "",
1476
+ compression_mode: str = "standard",
1477
+ protected_colors: Optional[list] = None,
1478
+ dithering: bool = True,
1479
+ retry: bool = False,
1480
+ skip_existing: bool = False,
1481
+ keep_exif: bool = False,
1482
+ overrides: Optional[dict] = None,
1483
+ batch_state: Optional[dict] = None,
1484
+ ):
1485
+ if optimizer is None:
1486
+ state.logs.append("Optimizer not initialized")
1487
+ state.is_running = False
1488
+ return
1489
+
1490
+ overrides = overrides or {}
1491
+
1492
+ # Remember the persistent output folder of this run (if any) so
1493
+ # /api/reveal can open it directly — the endpoint never trusts a
1494
+ # client-supplied folder path, only this server-side record. Cleared
1495
+ # again for temp-workspace-only runs.
1496
+ state.output_dir = str(Path(output_dir).resolve()) if output_dir else None
1497
+
1498
+ # Build a path→entry lookup for batch state persistence — O(1) per file
1499
+ # instead of scanning the whole list each time. Only populated when a
1500
+ # batch_state was provided (resume flow).
1501
+ _bs_lookup: dict[str, dict] = {}
1502
+ if batch_state:
1503
+ for _f in batch_state.get("files", []):
1504
+ _bs_lookup[_f["path"]] = _f
1505
+
1506
+ # rel_path -> fingerprint of the settings that produced the file
1507
+ # currently at that path in output_dir. Loaded once here (not
1508
+ # per-file — this file can grow to one entry per image ever produced
1509
+ # into this folder, so re-reading/re-writing it from disk on every
1510
+ # single file would be O(n) work repeated n times) and only written
1511
+ # back to disk if something actually changes. Tracked for every run
1512
+ # with a persistent output_dir, not just skip_existing runs — a very
1513
+ # common pattern is "run normally once, then re-run with
1514
+ # skip_existing checked", and that first normal run needs to have
1515
+ # left a fingerprint behind for the second run to have anything to
1516
+ # verify against. See skip_existing's reuse check below and
1517
+ # _settings_fingerprint for why this exists: mtime alone can't tell
1518
+ # "unchanged source, same settings, safe to reuse" apart from
1519
+ # "unchanged source, but the user asked for different settings this
1520
+ # run" — before this, skip_existing couldn't tell those apart and
1521
+ # silently reused stale output for the latter.
1522
+ _skip_fp = _load_skip_fingerprints(output_dir) if output_dir else {}
1523
+ _skip_fp_dirty = False
1524
+
1525
+ ws = state.workspace
1526
+ opt_output_dir = ws / "output"
1527
+ if opt_output_dir.exists() and not retry:
1528
+ # Off the event loop: a leftover output dir from a previous run could
1529
+ # hold thousands of files; deleting them synchronously here would
1530
+ # block the worker spawn below (and any other concurrent async work
1531
+ # in this process) for the duration of the unlink.
1532
+ #
1533
+ # Skipped ONLY on a retry: the earlier run's successful outputs live
1534
+ # in here, and retry only re-runs the previously-failed files —
1535
+ # wiping the dir would delete good results (breaking their Compare
1536
+ # links and the download ZIP) just to regenerate a few failures.
1537
+ #
1538
+ # skip_existing does NOT suppress the wipe. Its purpose is purely
1539
+ # per-file ("can this file be reused instead of recompressed?"), and
1540
+ # the reuse path copies from output_dir back into ws/output anyway —
1541
+ # it never relies on ws/output surviving. Coupling the wipe to it
1542
+ # meant a normal subset run with skip_existing on would leave last
1543
+ # run's now-unselected outputs in ws/output, and the whole-dir ZIP
1544
+ # build would then leak those stale files into the download even
1545
+ # though they aren't in this run's results/selection.
1546
+ await _async_rmtree(opt_output_dir)
1547
+ opt_output_dir.mkdir(parents=True, exist_ok=True)
1548
+
1549
+ # A per-file output_format override changes that file's suffix (and thus
1550
+ # its collision slot) — see _resolve_collision_free_output_paths for the
1551
+ # actual algorithm this now shares with CLI mode.
1552
+ #
1553
+ # Seed used_names with output_name values state.results already holds
1554
+ # (previous_results on resume; the kept, non-retried results on retry)
1555
+ # — otherwise a name already claimed by one of those doesn't block a
1556
+ # *new* item in this call from being assigned it too, since each call
1557
+ # to _resolve_collision_free_output_paths only sees the items passed to
1558
+ # it. See that function's docstring for the resume scenario this fixes.
1559
+ _reserved_output_names = {
1560
+ str(opt_output_dir / r["output_name"]).lower()
1561
+ for r in state.results if r.get("output_name")
1562
+ }
1563
+ out_paths = _resolve_collision_free_output_paths(
1564
+ [
1565
+ (f["id"], f["name"], overrides.get(f["id"], {}).get("output_format", output_format))
1566
+ for f in files
1567
+ ],
1568
+ opt_output_dir,
1569
+ reserved_names=_reserved_output_names,
1570
+ )
1571
+
1572
+ async def log(msg):
1573
+ state.logs.append(f" {msg}")
1574
+
1575
+ async def process_one(file_info: dict):
1576
+ input_path = Path(file_info["path"])
1577
+
1578
+ # file_info["name"] is always the clean, structure-preserving
1579
+ # relative name (e.g. "2023/vacation/IMG_0001.png") for both the
1580
+ # scan and upload flows — out_paths derives from it directly rather
1581
+ # than from the physical storage path, which for uploads is
1582
+ # intentionally flattened/deduplicated and does NOT mirror the
1583
+ # original folder structure.
1584
+ out_path = out_paths[file_info["id"]]
1585
+ if out_path is None:
1586
+ raise ValueError("unsafe file name escapes the output directory")
1587
+ out_path.parent.mkdir(parents=True, exist_ok=True)
1588
+
1589
+ # Resolve this file's effective parameters: a per-file override
1590
+ # (overrides[file_id]) wins for any field it lists, otherwise the
1591
+ # top-level defaults apply. out_path was already allocated with the
1592
+ # effective output_format, so they stay consistent.
1593
+ ov = overrides.get(file_info["id"], {})
1594
+ eff_quality = ov.get("quality", quality)
1595
+ eff_max_width = ov.get("max_width", max_width)
1596
+ eff_compression_mode = ov.get("compression_mode", compression_mode)
1597
+ eff_protected_colors = ov.get("protected_colors", protected_colors)
1598
+ eff_dithering = ov.get("dithering", dithering)
1599
+ eff_keep_exif = ov.get("keep_exif", keep_exif)
1600
+ eff_output_format = ov.get("output_format", output_format)
1601
+
1602
+ # Skip-already-optimized: if the user re-runs against the same output
1603
+ # folder and this file's target is already there, reuse it instead of
1604
+ # paying pngquant/oxipng again. We still copy it back into ws/output so
1605
+ # Compare/preview (/api/result) and the download ZIP keep working — the
1606
+ # copy is cheap next to a re-compress. No-op without output_dir (the
1607
+ # temp workspace is wiped/empty each fresh run, nothing to reuse).
1608
+ # _is_valid_reusable_output guards against reusing a truncated/corrupt
1609
+ # leftover from a previous run that was interrupted mid-write — a
1610
+ # non-empty file alone isn't proof it's complete.
1611
+ # Staleness: reuse is only valid if the *source* hasn't changed since
1612
+ # the existing output was produced, AND this run's effective
1613
+ # settings match whatever produced it. Same filename doesn't mean
1614
+ # same content — e.g. a screenshot re-taken under the same name —
1615
+ # and an unchanged source doesn't mean the user wants the same
1616
+ # output either: they may have just changed quality/mode/max_width/
1617
+ # format/etc. and re-run with skip_existing still on, expecting
1618
+ # their new settings to apply. mtime alone can't tell those two
1619
+ # cases apart (confirmed empirically: changing max_width between
1620
+ # runs with an untouched source silently kept the old, un-resized
1621
+ # output). There's no manifest recording "this output came from
1622
+ # source hash X" written into the user's real output folder (still
1623
+ # deliberately avoided — see _settings_fingerprint), so the mtime
1624
+ # check (make/rsync -u style: source newer than target => changed)
1625
+ # is combined with a settings fingerprint stored separately under
1626
+ # this app's own config dir. No recorded fingerprint (e.g. the
1627
+ # first skip_existing run against files produced before this
1628
+ # existed) means "unverifiable" — recompress rather than trust it,
1629
+ # same conservative direction the upload-flow mtime case already
1630
+ # fails in.
1631
+ # Note: a skip decision means the file is NOT recompressed at all,
1632
+ # so a per-file override only has an effect on a skipped file
1633
+ # indirectly — by changing its fingerprint and thereby causing a
1634
+ # miss on settings_unchanged below, which forces a recompress
1635
+ # (where the override then genuinely applies). An override whose
1636
+ # values happen to match what's already in place doesn't change
1637
+ # anything either way, by design (nothing to apply that wasn't
1638
+ # already true).
1639
+ if skip_existing and output_dir:
1640
+ rel = out_path.relative_to(opt_output_dir)
1641
+ dest = Path(output_dir) / rel
1642
+ source_unchanged = (
1643
+ input_path.exists() and dest.exists()
1644
+ and input_path.stat().st_mtime <= dest.stat().st_mtime
1645
+ )
1646
+ eff_fingerprint = _settings_fingerprint(
1647
+ eff_quality, eff_compression_mode, eff_max_width,
1648
+ eff_protected_colors, eff_dithering, eff_keep_exif, eff_output_format,
1649
+ )
1650
+ settings_unchanged = _skip_fp.get(str(rel)) == eff_fingerprint
1651
+ if (
1652
+ source_unchanged
1653
+ and settings_unchanged
1654
+ and dest.stat().st_size > 0
1655
+ and _is_valid_reusable_output(dest, eff_output_format)
1656
+ ):
1657
+ shutil.copy2(dest, out_path)
1658
+ orig_size = input_path.stat().st_size if input_path.exists() else 0
1659
+ comp_size = dest.stat().st_size
1660
+ savings = orig_size - comp_size
1661
+ skipped_result = {
1662
+ "id": file_info["id"],
1663
+ "name": file_info["name"],
1664
+ "original_path": file_info["path"],
1665
+ "output_format": eff_output_format,
1666
+ "output_name": str(rel),
1667
+ "success": True,
1668
+ "skipped": True,
1669
+ "original_size": orig_size,
1670
+ "compressed_size": comp_size,
1671
+ "savings": savings,
1672
+ "savings_percent": round(savings / orig_size * 100, 1) if orig_size > 0 else 0,
1673
+ # Absolute path to the actual file on disk, so the
1674
+ # frontend can offer "Reveal in File Explorer" — only
1675
+ # meaningful when output_dir is a real, persistent
1676
+ # folder (this whole branch is gated on output_dir
1677
+ # being set, so dest is always a real path here, not a
1678
+ # temp workspace file that disappears after cleanup).
1679
+ "final_output_path": str(dest),
1680
+ }
1681
+ state.logs.append(f" SKIP {file_info['name']} (already optimized)")
1682
+ state.results.append(skipped_result)
1683
+ # Persist to batch state — a skipped file is "done"
1684
+ if file_info["path"] in _bs_lookup:
1685
+ _bs_lookup[file_info["path"]]["status"] = "done"
1686
+ batch_state.setdefault("results", []).append(skipped_result)
1687
+ _save_batch_state(batch_state)
1688
+ return
1689
+
1690
+ state.logs.append(f"Processing: {file_info['name']}")
1691
+
1692
+ result = await optimizer.optimize_png(
1693
+ input_path=input_path,
1694
+ output_path=out_path,
1695
+ quality=eff_quality,
1696
+ max_width=eff_max_width,
1697
+ compression_mode=eff_compression_mode,
1698
+ protected_colors=eff_protected_colors,
1699
+ dithering=eff_dithering,
1700
+ output_format=eff_output_format,
1701
+ progress_callback=log,
1702
+ keep_exif=eff_keep_exif,
1703
+ )
1704
+
1705
+ result["id"] = file_info["id"]
1706
+ result["name"] = file_info["name"]
1707
+ result["original_path"] = file_info["path"]
1708
+ result["output_format"] = eff_output_format
1709
+ # The actual output location relative to ws/output — may differ
1710
+ # from name+suffix when a collision was disambiguated above, so
1711
+ # consumers (e.g. /api/preview) must use this instead of
1712
+ # re-deriving it from "name".
1713
+ result["output_name"] = str(out_path.relative_to(opt_output_dir))
1714
+
1715
+ if result["success"]:
1716
+ result["savings"] = result["original_size"] - result["compressed_size"]
1717
+ result["savings_percent"] = round(
1718
+ result["savings"] / result["original_size"] * 100, 1
1719
+ ) if result["original_size"] > 0 else 0
1720
+ state.logs.append(
1721
+ f" OK {file_info['name']}: {_fmt_size(result['original_size'])} -> "
1722
+ f"{_fmt_size(result['compressed_size'])} (saved {result['savings_percent']}%)"
1723
+ )
1724
+ # Copy this file to the user's chosen output folder right away,
1725
+ # rather than waiting for the whole batch to finish — otherwise
1726
+ # the folder stays empty for the entire run, which looks like
1727
+ # the wrong folder was picked.
1728
+ if output_dir:
1729
+ try:
1730
+ user_output = Path(output_dir)
1731
+ rel = out_path.relative_to(opt_output_dir)
1732
+ dest = user_output / rel
1733
+ dest.parent.mkdir(parents=True, exist_ok=True)
1734
+ shutil.copy2(out_path, dest)
1735
+ # Same reasoning as the skip_existing branch above:
1736
+ # only set when there's a real, persistent file on
1737
+ # disk to reveal (nothing to show when output_dir is
1738
+ # empty and results live only in the temp workspace).
1739
+ result["final_output_path"] = str(dest)
1740
+ # Record what settings actually produced this file, so
1741
+ # a later skip_existing run can tell "safe to reuse"
1742
+ # apart from "source unchanged but settings differ" —
1743
+ # see the fingerprint check above. Tracked on every
1744
+ # run with a persistent output_dir (not just
1745
+ # skip_existing runs) so a plain run followed by a
1746
+ # skip_existing run has something to verify against.
1747
+ nonlocal _skip_fp_dirty
1748
+ _skip_fp[str(rel)] = _settings_fingerprint(
1749
+ eff_quality, eff_compression_mode, eff_max_width,
1750
+ eff_protected_colors, eff_dithering, eff_keep_exif, eff_output_format,
1751
+ )
1752
+ _skip_fp_dirty = True
1753
+ except Exception as e:
1754
+ state.logs.append(f" Output copy failed: {e}")
1755
+ else:
1756
+ state.logs.append(f" FAILED {file_info['name']}: {result.get('error', 'unknown')}")
1757
+
1758
+ # The progress bump moved to _run_worker_pool's on_item_done — see
1759
+ # the No-lock-note there (same single-threaded-cooperative reasoning
1760
+ # applies: state.results.append + on_item_done's state.current += 1
1761
+ # have no `await` between them, so no other worker interleaves).
1762
+ state.results.append(result)
1763
+
1764
+ # Persist per-file status to batch_state.json — this is what lets
1765
+ # a crashed / restarted server pick up where it left off. Written
1766
+ # inside process_one (not on_item_done) because the result dict
1767
+ # with success/failure lives here; on_item_done only bumps the counter.
1768
+ if file_info["path"] in _bs_lookup:
1769
+ _bs_lookup[file_info["path"]]["status"] = "done" if result.get("success") else "failed"
1770
+ batch_state.setdefault("results", []).append(result)
1771
+ _save_batch_state(batch_state)
1772
+
1773
+ def on_item_error(file_info, e):
1774
+ # Anything process_one doesn't already catch internally (optimize_png
1775
+ # has its own try/except, but e.g. mkdir permission errors or a
1776
+ # malformed file_info wouldn't be) lands here. Degrading to a
1777
+ # normal failed-file result keeps one bad file from taking down the
1778
+ # whole batch — see test_concurrency.test_one_file_raising_does_not_orphan_the_others.
1779
+ state.logs.append(f" FAILED {file_info.get('name', '?')}: {e}")
1780
+ state.results.append({
1781
+ "id": file_info.get("id"),
1782
+ "name": file_info.get("name"),
1783
+ "original_path": file_info.get("path"),
1784
+ "success": False,
1785
+ "error": str(e),
1786
+ "original_size": 0,
1787
+ "compressed_size": 0,
1788
+ })
1789
+ # Persist failure to batch state so resume picks it up
1790
+ if file_info.get("path") in _bs_lookup:
1791
+ _bs_lookup[file_info["path"]]["status"] = "failed"
1792
+ _save_batch_state(batch_state)
1793
+
1794
+ def on_item_done(_file_info):
1795
+ state.current += 1
1796
+
1797
+ try:
1798
+ await _run_worker_pool(
1799
+ files,
1800
+ process_one,
1801
+ n_workers=CONCURRENT_WORKERS,
1802
+ cancel_check=lambda: state.cancelled,
1803
+ pause_check=lambda: state.paused,
1804
+ on_item_error=on_item_error,
1805
+ on_item_done=on_item_done,
1806
+ )
1807
+ if state.cancelled:
1808
+ state.logs.append("Cancelled by user")
1809
+
1810
+ except Exception as e:
1811
+ state.logs.append(f" UNEXPECTED ERROR: {e}")
1812
+ import traceback
1813
+ state.logs.append(f" {traceback.format_exc()}")
1814
+
1815
+ finally:
1816
+ state.is_running = False
1817
+ # Outputs for this run are now final — invalidate any cached ZIP so the
1818
+ # next download rebuilds (see download_zip). Bumped once per run (fresh
1819
+ # or retry), which is exactly when ws/output contents change.
1820
+ state.output_version += 1
1821
+ total_orig = sum(r["original_size"] for r in state.results if r["success"])
1822
+ total_comp = sum(r["compressed_size"] for r in state.results if r["success"])
1823
+ saved = total_orig - total_comp
1824
+ pct = round(saved / total_orig * 100, 1) if total_orig > 0 else 0
1825
+ state.logs.append(
1826
+ f"\nDone! {state.current}/{state.total} files, "
1827
+ f"saved {_fmt_size(saved)} ({pct}%)"
1828
+ )
1829
+ if output_dir:
1830
+ state.logs.append(f" Output saved to: {Path(output_dir).resolve()}")
1831
+ # Batch state: clear only when every file is done (no resume needed).
1832
+ # If some are still pending/failed (cancel, crash, partial failure),
1833
+ # leave the file on disk so the frontend can offer a Resume button.
1834
+ if batch_state:
1835
+ remaining = [f for f in batch_state.get("files", []) if f["status"] in ("pending", "failed")]
1836
+ if not remaining and batch_state.get("output_dir"):
1837
+ _clear_batch_state(batch_state["output_dir"])
1838
+ # Persist any new/updated skip_existing fingerprints from this run
1839
+ # in one write, rather than one disk write per file (see the load
1840
+ # site's comment for why). A cancelled/crashed run still saves
1841
+ # whatever completed before the interruption — those files are
1842
+ # genuinely done and their fingerprints are genuinely accurate.
1843
+ if _skip_fp_dirty:
1844
+ _save_skip_fingerprints(output_dir, _skip_fp)
1845
+
1846
+
1847
+ @app.get("/api/progress")
1848
+ async def get_progress(
1849
+ state: AppState = Depends(get_session),
1850
+ since_result: int = 0,
1851
+ since_log: Optional[int] = None,
1852
+ ):
1853
+ # Incremental cursor: the frontend passes how many results/log lines it
1854
+ # has already received so we only send the tail. For a few-thousand-file
1855
+ # batch, re-sending the whole results array every 400ms poll was O(n) per
1856
+ # poll / O(n^2) over the run — the dominant client-side cost. Slicing from
1857
+ # a cursor makes each result/log line travel exactly once (O(n) total).
1858
+ #
1859
+ # Backward compatible: since_result defaults to 0 (results[0:] == full) and
1860
+ # since_log defaults to None (last-100 lines, the original behavior), so
1861
+ # callers/tests that omit the params see the pre-existing full payload.
1862
+ return JSONResponse({
1863
+ "running": state.is_running,
1864
+ "paused": state.paused,
1865
+ "current": state.current,
1866
+ "total": state.total,
1867
+ "logs": state.logs[since_log:] if since_log is not None else state.logs[-100:],
1868
+ "results": state.results[since_result:],
1869
+ "result_total": len(state.results),
1870
+ "log_total": len(state.logs),
1871
+ })
1872
+
1873
+
1874
+ def _sse_format(event_type: str, data, eid: Optional[str]) -> str:
1875
+ """Format one SSE message. `id` (when given) encodes the cumulative
1876
+ (result, log) cursor as `r{R}:l{L}` so a client can reattach via
1877
+ Last-Event-ID and replay only the tail — same cursor semantics the
1878
+ polling /api/progress endpoint uses with since_result/since_log."""
1879
+ import json as _json
1880
+ parts = []
1881
+ if eid is not None:
1882
+ parts.append(f"id: {eid}")
1883
+ parts.append(f"event: {event_type}")
1884
+ parts.append(f"data: {_json.dumps(data)}")
1885
+ return "\n".join(parts) + "\n\n"
1886
+
1887
+
1888
+ @app.get("/api/events")
1889
+ async def events(request: Request, state: AppState = Depends(get_session)):
1890
+ """SSE progress transport — the streaming counterpart to /api/progress.
1891
+
1892
+ Emits `result`, `log`, and `done` events. Each carries an `id` of the
1893
+ form `r{R}:l{L}` (results seen : logs seen), so a client that drops and
1894
+ reconnects sends `Last-Event-ID` and the server replays only the tail —
1895
+ reattach for a page refresh. The HTTP polling endpoint stays as the
1896
+ automatic fallback (SSE can be buffered/dropped by some proxies); the
1897
+ two read the same state so they always agree.
1898
+
1899
+ No app-token requirement (mirrors /api/progress — both are read-only,
1900
+ and EventSource can't send custom headers anyway). Session-scoped via
1901
+ the cookie EventSource sends same-origin.
1902
+
1903
+ A `: keepalive` comment is emitted every few idle seconds so
1904
+ intermediate proxies don't time out an open but quiet connection."""
1905
+ last_id = request.headers.get("last-event-id", "")
1906
+ r_cur, l_cur = 0, 0
1907
+ if last_id:
1908
+ for part in last_id.split(":"):
1909
+ if part.startswith("r"):
1910
+ try:
1911
+ r_cur = max(0, int(part[1:]))
1912
+ except ValueError:
1913
+ r_cur = 0
1914
+ elif part.startswith("l"):
1915
+ try:
1916
+ l_cur = max(0, int(part[1:]))
1917
+ except ValueError:
1918
+ l_cur = 0
1919
+
1920
+ async def event_stream():
1921
+ nonlocal r_cur, l_cur
1922
+ last_emit = time.time()
1923
+ # A pause/resume can happen with no new results/logs to piggyback
1924
+ # on (the whole point of "soft pause" is new work stops getting
1925
+ # scheduled), so paused-state changes get their own event rather
1926
+ # than waiting for the next result/log — otherwise a client has no
1927
+ # way to learn about it until the run's `done` event, which for a
1928
+ # long pause could be a very long wait.
1929
+ last_paused_sent = state.paused
1930
+ yield _sse_format("status", {
1931
+ "paused": state.paused, "current": state.current, "total": state.total,
1932
+ }, f"r{r_cur}:l{l_cur}")
1933
+ while True:
1934
+ if state.paused != last_paused_sent:
1935
+ last_paused_sent = state.paused
1936
+ yield _sse_format("status", {
1937
+ "paused": state.paused, "current": state.current, "total": state.total,
1938
+ }, f"r{r_cur}:l{l_cur}")
1939
+ last_emit = time.time()
1940
+
1941
+ # Emit any new results since the cursor.
1942
+ for res in state.results[r_cur:]:
1943
+ r_cur += 1
1944
+ yield _sse_format("result", res, f"r{r_cur}:l{l_cur}")
1945
+ last_emit = time.time()
1946
+ # Emit any new log lines since the cursor.
1947
+ for line in state.logs[l_cur:]:
1948
+ l_cur += 1
1949
+ yield _sse_format("log", {"line": line}, f"r{r_cur}:l{l_cur}")
1950
+ last_emit = time.time()
1951
+
1952
+ if not state.is_running:
1953
+ # The run's finally block sets is_running=False BEFORE
1954
+ # appending the final "Done!" summary log, so sleep a beat
1955
+ # and drain once more to catch it, then close with `done`.
1956
+ await asyncio.sleep(0.05)
1957
+ for res in state.results[r_cur:]:
1958
+ r_cur += 1
1959
+ yield _sse_format("result", res, f"r{r_cur}:l{l_cur}")
1960
+ for line in state.logs[l_cur:]:
1961
+ l_cur += 1
1962
+ yield _sse_format("log", {"line": line}, f"r{r_cur}:l{l_cur}")
1963
+ yield _sse_format("done", {
1964
+ "running": False,
1965
+ "paused": state.paused,
1966
+ "current": state.current,
1967
+ "total": state.total,
1968
+ "result_total": len(state.results),
1969
+ "log_total": len(state.logs),
1970
+ }, f"r{r_cur}:l{l_cur}")
1971
+ return
1972
+
1973
+ # Heartbeat: if nothing was emitted for a while, send a comment
1974
+ # so proxies buffering idle connections don't drop the stream.
1975
+ if time.time() - last_emit > 5:
1976
+ yield ": keepalive\n\n"
1977
+ last_emit = time.time()
1978
+
1979
+ # Detect a client that's gone away (tab closed, navigated off,
1980
+ # network drop) explicitly rather than relying solely on the
1981
+ # ASGI layer to raise GeneratorExit into us on the next yield —
1982
+ # that's the common case, but this loop spends most of its time
1983
+ # in asyncio.sleep() rather than yielding, so a disconnect could
1984
+ # otherwise go unnoticed for a while and leave the generator
1985
+ # (and its reference to `state`) alive longer than it should be.
1986
+ if await request.is_disconnected():
1987
+ return
1988
+
1989
+ await asyncio.sleep(0.1)
1990
+
1991
+ return StreamingResponse(
1992
+ event_stream(),
1993
+ media_type="text/event-stream",
1994
+ headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no", "Connection": "keep-alive"},
1995
+ )
1996
+
1997
+
1998
+ @app.post("/api/cancel")
1999
+ async def cancel(state: AppState = Depends(get_session), _auth: None = Depends(require_token)):
2000
+ state.cancelled = True
2001
+ return JSONResponse({"ok": True})
2002
+
2003
+
2004
+ @app.post("/api/pause")
2005
+ async def pause(state: AppState = Depends(get_session), _auth: None = Depends(require_token)):
2006
+ """Soft pause: the worker pool stops scheduling NEW files, but any file
2007
+ already mid-compression (its pngquant/oxipng subprocess running) finishes
2008
+ naturally — no process kill. Resume drains the rest. Only valid while a
2009
+ run is actually in progress; pausing an idle session is a no-op error."""
2010
+ if not state.is_running:
2011
+ return JSONResponse({"error": "No optimization in progress"}, status_code=400)
2012
+ state.paused = True
2013
+ return JSONResponse({"ok": True})
2014
+
2015
+
2016
+ @app.post("/api/resume")
2017
+ async def resume(state: AppState = Depends(get_session), _auth: None = Depends(require_token)):
2018
+ if not state.paused:
2019
+ return JSONResponse({"error": "Not paused"}, status_code=400)
2020
+ state.paused = False
2021
+ return JSONResponse({"ok": True})
2022
+
2023
+
2024
+ @app.post("/api/preview-optimize")
2025
+ async def preview_optimize(data: PreviewRequest, state: AppState = Depends(get_session), _auth: None = Depends(require_token)):
2026
+ """Single-file dry run: project the compressed size of one file under
2027
+ the current settings WITHOUT touching the batch state machine.
2028
+
2029
+ Reuses `optimizer.optimize_png` but writes to a temp file under
2030
+ ws/preview (never ws/output, which the download ZIP rglobs), measures
2031
+ the size, then deletes the temp. Must NOT mutate state.results /
2032
+ state.current / state.total / state.output_version / state.logs /
2033
+ state.is_running, and must NOT copy anything into a persistent
2034
+ output_dir.
2035
+
2036
+ Allowed while a batch is running — it only contends for the optimizer
2037
+ semaphore, never for batch state. The progress_callback is a no-op so
2038
+ preview progress doesn't leak into the batch's live log."""
2039
+ if optimizer is None:
2040
+ return JSONResponse({"error": "Optimizer not initialized"}, status_code=503)
2041
+ # Same validation as /api/optimize (now literally the same function), so
2042
+ # a preview reflects what the real run would actually accept.
2043
+ err = _validate_optimize_settings(
2044
+ data.quality, data.output_format, data.compression_mode, data.max_width, data.protected_colors,
2045
+ )
2046
+ if err:
2047
+ return JSONResponse({"error": err}, status_code=400)
2048
+
2049
+ file_info = next((f for f in state.files if f.get("id") == data.file_id), None)
2050
+ if file_info is None:
2051
+ return JSONResponse({"error": "File not found"}, status_code=404)
2052
+ if not state.workspace:
2053
+ return JSONResponse({"error": "No active workspace"}, status_code=400)
2054
+
2055
+ preview_dir = state.workspace / "preview"
2056
+ preview_dir.mkdir(parents=True, exist_ok=True)
2057
+ out_path = preview_dir / f"{data.file_id}.{data.output_format}"
2058
+ try:
2059
+ out_path.unlink(missing_ok=True)
2060
+ except Exception:
2061
+ pass
2062
+
2063
+ input_path = Path(file_info["path"])
2064
+ original_size = input_path.stat().st_size if input_path.exists() else 0
2065
+
2066
+ async def _noop_progress(_msg):
2067
+ pass
2068
+
2069
+ try:
2070
+ result = await optimizer.optimize_png(
2071
+ input_path=input_path,
2072
+ output_path=out_path,
2073
+ quality=data.quality,
2074
+ max_width=data.max_width,
2075
+ compression_mode=data.compression_mode,
2076
+ protected_colors=data.protected_colors,
2077
+ dithering=data.dithering,
2078
+ output_format=data.output_format,
2079
+ progress_callback=_noop_progress,
2080
+ keep_exif=data.keep_exif,
2081
+ )
2082
+ finally:
2083
+ # Best-effort cleanup of the preview temp. optimize_png's own
2084
+ # finally-sweep already removes its *.src.png/*.pngquant.png/etc
2085
+ # sidecars; this removes the final output file too so ws/preview
2086
+ # never accumulates and can't leak into anything.
2087
+ try:
2088
+ out_path.unlink(missing_ok=True)
2089
+ except Exception:
2090
+ pass
2091
+
2092
+ compressed_size = result.get("compressed_size", 0) if result.get("success") else 0
2093
+ savings = original_size - compressed_size
2094
+ pct = round(savings / original_size * 100, 1) if original_size > 0 else 0
2095
+ return JSONResponse({
2096
+ "success": result["success"],
2097
+ "original_size": original_size,
2098
+ "compressed_size": compressed_size,
2099
+ "savings": savings,
2100
+ "savings_percent": pct,
2101
+ "error": result.get("error"),
2102
+ "warning": result.get("warning"),
2103
+ })
2104
+
2105
+
2106
+ @app.get("/api/source-file/{ws_name}/{file_id}")
2107
+ async def get_source_file(ws_name: str, file_id: str, state: AppState = Depends(get_session)):
2108
+ if state.workspace and state.workspace.name == ws_name:
2109
+ for f in state.files:
2110
+ if f["id"] == file_id:
2111
+ p = Path(f["path"])
2112
+ if p.exists():
2113
+ return FileResponse(str(p), media_type=_media_type_for(p))
2114
+ for r in state.results:
2115
+ if r.get("id") == file_id:
2116
+ p = Path(r["original_path"])
2117
+ if p.exists():
2118
+ return FileResponse(str(p), media_type=_media_type_for(p))
2119
+ return Response(status_code=404)
2120
+
2121
+
2122
+ def _resolve_result_file(state: "AppState", result_path: str) -> Optional[Path]:
2123
+ """Locate a completed result's output image on disk.
2124
+
2125
+ Prefers the live workspace copy. Falls back to the copy already placed
2126
+ in the user's chosen output folder (result["final_output_path"], written
2127
+ immediately as each file finishes — see _process_files) for results
2128
+ that were restored on resume: state.workspace is a fresh temp dir every
2129
+ process start (new_workspace), so a result completed before a server
2130
+ restart never has a file at the workspace path even though it's a
2131
+ legitimate result of this session.
2132
+ """
2133
+ if state.workspace:
2134
+ p = (state.workspace / "output" / result_path).resolve()
2135
+ base = str((state.workspace / "output").resolve())
2136
+ if p.exists() and (str(p) == base or str(p).startswith(base + os.sep)):
2137
+ return p
2138
+ for r in state.results:
2139
+ if r.get("output_name") == result_path and r.get("final_output_path"):
2140
+ fp = Path(r["final_output_path"])
2141
+ if fp.exists():
2142
+ return fp
2143
+ return None
2144
+
2145
+
2146
+ @app.get("/api/result/{ws_name}/{result_path:path}")
2147
+ async def get_result(ws_name: str, result_path: str, state: AppState = Depends(get_session)):
2148
+ if state.workspace and state.workspace.name == ws_name:
2149
+ p = _resolve_result_file(state, result_path)
2150
+ if p:
2151
+ return FileResponse(str(p), media_type=_media_type_for(p))
2152
+ return Response(status_code=404)
2153
+
2154
+
2155
+ @app.get("/api/preview/{ws_name}/{file_id}")
2156
+ async def preview(ws_name: str, file_id: str, request: Request, state: AppState = Depends(get_session)):
2157
+ # Same ownership check as every other workspace-scoped endpoint. Doing
2158
+ # it FIRST also closes a reflected-XSS hole: ws_name is an arbitrary
2159
+ # URL path segment that gets embedded in the HTML below — without this
2160
+ # gate (plus the html.escape on the URLs), a crafted ws_name like
2161
+ # `"><script>...` would execute in this app's origin and could then
2162
+ # harvest APP_TOKEN from the index page, defeating the CSRF defense.
2163
+ # This page is opened in a new tab (see index.html's `${previewUrl}`,
2164
+ # which appends the caller's current UI language as ?lang=), so it
2165
+ # can't read the main page's localStorage directly — the query param
2166
+ # is how the language choice crosses that boundary. Anything other
2167
+ # than a known key falls back to English; this dict is standalone
2168
+ # from index.html's I18N (different runtime, server- vs client-
2169
+ # rendered) and needs updating in step with it for new languages.
2170
+ lang = request.query_params.get("lang", "en")
2171
+ T = PREVIEW_I18N.get(lang, PREVIEW_I18N["en"])
2172
+ if not (state.workspace and state.workspace.name == ws_name):
2173
+ return HTMLResponse(f"<h2>{T['not_found']}</h2>", status_code=404)
2174
+ html = """<!DOCTYPE html>
2175
+ <html><head><meta charset="utf-8">
2176
+ <style>
2177
+ *{margin:0;padding:0;box-sizing:border-box}
2178
+ body{background:#f5f5f0;color:#333;font-family:system-ui,sans-serif;display:flex;flex-direction:column;height:100vh}
2179
+ .bar{background:#fff;padding:12px 20px;display:flex;justify-content:space-between;align-items:center;border-bottom:1px solid #ddd;font-size:14px;box-shadow:0 1px 3px rgba(0,0,0,.08)}
2180
+ .bar .title{font-weight:600;color:#555}
2181
+ .bar .stats{color:#888}
2182
+ .view-toggle{display:flex;gap:4px}
2183
+ .view-btn{padding:4px 10px;font-size:12px;border:1px solid #ddd;background:#fff;border-radius:4px;cursor:pointer;color:#666}
2184
+ .view-btn.active{background:#333;color:#fff;border-color:#333}
2185
+ .container{flex:1;display:flex}
2186
+ .panel{flex:1;display:flex;flex-direction:column;overflow:hidden}
2187
+ .panel:first-child{border-right:1px solid #ddd}
2188
+ .label{padding:8px 16px;font-size:12px;text-transform:uppercase;letter-spacing:1px;color:#888;background:#fafaf5}
2189
+ .label .info{display:block;text-transform:none;letter-spacing:normal;color:#aaa;margin-top:2px;font-size:11px}
2190
+ .image-wrap{flex:1;display:flex;align-items:center;justify-content:center;overflow:auto;padding:16px;background:#f0f0eb}
2191
+ .image-wrap img{max-width:100%;max-height:100%;object-fit:contain}
2192
+ .image-wrap.zoom-100{align-items:flex-start;justify-content:flex-start}
2193
+ .image-wrap img.zoom-100{max-width:none;max-height:none;width:auto;height:auto}
2194
+ .footer{padding:10px 20px;text-align:center;font-size:13px;border-top:1px solid #ddd;color:#999}
2195
+ .overlay-view{flex:1;display:flex;flex-direction:column}
2196
+ .overlay-label{padding:8px 16px;font-size:12px;text-align:center;color:#888;background:#fafaf5;user-select:none}
2197
+ .overlay-wrap{flex:1;position:relative;overflow:auto;background:#f0f0eb;cursor:pointer}
2198
+ .overlay-img{position:absolute;top:16px;left:16px;width:calc(100% - 32px);height:calc(100% - 32px);object-fit:contain}
2199
+ .overlay-img.zoom-100{position:static;width:auto;height:auto;max-width:none;max-height:none;margin:16px}
2200
+ .zoom-toggle{display:flex;gap:4px}
2201
+ .slider-view{flex:1;display:flex;flex-direction:column}
2202
+ .slider-label{padding:8px 16px;font-size:12px;text-transform:uppercase;letter-spacing:1px;color:#888;background:#fafaf5;user-select:none;display:flex;justify-content:space-between;gap:16px}
2203
+ .slider-label .side{min-width:0}
2204
+ .slider-label .side.right{text-align:right}
2205
+ .slider-label .info{display:block;text-transform:none;letter-spacing:normal;color:#aaa;margin-top:2px;font-size:11px}
2206
+ .slider-wrap{flex:1;position:relative;overflow:hidden;background:#f0f0eb;touch-action:none;--pos:50%}
2207
+ .slider-wrap.zoom-100{overflow:auto}
2208
+ .slider-img{position:absolute;top:0;left:0;width:100%;height:100%;object-fit:contain;pointer-events:none;user-select:none}
2209
+ .slider-wrap.zoom-100 .slider-img{top:0;left:0;width:auto;height:auto;object-fit:none}
2210
+ .slider-top{clip-path:inset(0 calc(100% - var(--pos)) 0 0)}
2211
+ .slider-handle{position:absolute;top:0;bottom:0;left:var(--pos);width:32px;margin-left:-16px;cursor:ew-resize;display:flex;align-items:center;justify-content:center;touch-action:none}
2212
+ .slider-handle::before{content:"";position:absolute;top:0;bottom:0;left:50%;width:2px;background:#fff;box-shadow:0 0 0 1px rgba(0,0,0,.25);transform:translateX(-50%)}
2213
+ .slider-handle-grip{position:relative;width:28px;height:28px;border-radius:50%;background:#fff;box-shadow:0 1px 4px rgba(0,0,0,.35);display:flex;align-items:center;justify-content:center;color:#666;font-size:13px}
2214
+ </style>
2215
+ </head><body>"""
2216
+ result = None
2217
+ for r in state.results:
2218
+ if r.get("id") == file_id:
2219
+ result = r
2220
+ break
2221
+
2222
+ if not result:
2223
+ return HTMLResponse(f"<h2>{T['not_found']}</h2>", status_code=404)
2224
+
2225
+ import html as _html
2226
+
2227
+ orig_url = _html.escape(f"/api/source-file/{ws_name}/{file_id}", quote=True)
2228
+
2229
+ # Use the exact output path recorded by _process_files — it may carry a
2230
+ # collision-disambiguated name ("photo_2.png") that can't be re-derived
2231
+ # from result["name"]. Fallback keeps old sessions/results working.
2232
+ out_fmt = result.get("output_format", "png")
2233
+ comp_rel = result.get("output_name") or str(Path(result["name"]).with_suffix(f".{out_fmt}"))
2234
+
2235
+ comp_url = _html.escape(f"/api/result/{ws_name}/{comp_rel}", quote=True) if comp_rel else ""
2236
+
2237
+ # Same resolution _resolve_result_file uses for /api/result, applied
2238
+ # here too — this is the size/dimensions label shown next to the image,
2239
+ # and used to silently show "unavailable" for pre-restart results
2240
+ # before /api/result grew a fallback for them, even though the image
2241
+ # itself was reachable.
2242
+ orig_path = Path(result["original_path"]) if result.get("original_path") else None
2243
+ orig_info = _get_image_info(orig_path) if orig_path and orig_path.exists() else None
2244
+ comp_path = _resolve_result_file(state, comp_rel) if comp_rel else None
2245
+ comp_info = _get_image_info(comp_path) if comp_path else None
2246
+
2247
+ def _fmt_info(info: Optional[dict]) -> str:
2248
+ if not info:
2249
+ return T["info_unavailable"]
2250
+ return f"{info['width']}\u00d7{info['height']} \u00b7 {info['depth']}"
2251
+
2252
+ orig_info_text = _html.escape(_fmt_info(orig_info))
2253
+ comp_info_text = _html.escape(_fmt_info(comp_info))
2254
+
2255
+ safe_name = _html.escape(str(result['name']))
2256
+ safe_basename = _html.escape(Path(result['name']).name)
2257
+ title_prefix = _html.escape(T["title_prefix"])
2258
+ html = html.replace(
2259
+ '<head><meta charset="utf-8">',
2260
+ f'<head><meta charset="utf-8"><title>{title_prefix}{safe_basename}</title>',
2261
+ 1,
2262
+ )
2263
+ orig_size = _fmt_size(result['original_size'])
2264
+ comp_size = _fmt_size(result['compressed_size'])
2265
+ saved_text = _html.escape(T["saved"].format(pct=result.get('savings_percent', 0)))
2266
+ # Everything else here is a static, hardcoded-in-Python string (never
2267
+ # user/result data) safe to embed directly as a JS object literal. The
2268
+ # two info fields are the exception — orig_info_text/comp_info_text are
2269
+ # derived from the actual files (width/height ints plus a label from the
2270
+ # fixed _MODE_LABELS lookup) rather than hardcoded, but json.dumps
2271
+ # escapes them like everything else here, so the trust boundary for
2272
+ # this f-string page is unchanged.
2273
+ js_i18n = json.dumps({
2274
+ "original": T["original"],
2275
+ "compressed": T["compressed"],
2276
+ "toggle_suffix": T["toggle_suffix"],
2277
+ "footer_overlay": T["footer_overlay"],
2278
+ "footer_side": T["footer_side"],
2279
+ "footer_slider": T["footer_slider"],
2280
+ "zoom_hint": T["zoom_hint"],
2281
+ "orig_info": orig_info_text,
2282
+ "comp_info": comp_info_text,
2283
+ })
2284
+ html += f"""
2285
+ <div class="bar">
2286
+ <span class="title">{safe_name}</span>
2287
+ <span class="stats">{orig_size} -> {comp_size} | {saved_text}</span>
2288
+ <div class="view-toggle">
2289
+ <button class="view-btn" id="btn-side">{_html.escape(T['side_by_side'])}</button>
2290
+ <button class="view-btn active" id="btn-overlay">{_html.escape(T['overlay'])}</button>
2291
+ <button class="view-btn" id="btn-slider">{_html.escape(T['slider'])}</button>
2292
+ </div>
2293
+ <div class="zoom-toggle">
2294
+ <button class="view-btn active" id="btn-fit" title="{_html.escape(T['fit_title'])}">{_html.escape(T['fit'])}</button>
2295
+ <button class="view-btn" id="btn-zoom100" title="{_html.escape(T['zoom100_title'])}">{_html.escape(T['zoom100'])}</button>
2296
+ </div>
2297
+ </div>
2298
+ <div class="container" id="side-view" style="display:none">
2299
+ <div class="panel">
2300
+ <div class="label">{_html.escape(T['original_label'].format(size=orig_size))}<span class="info">{orig_info_text}</span></div>
2301
+ <div class="image-wrap" id="orig-wrap"><img src="{orig_url}" id="orig-img" alt="original"/></div>
2302
+ </div>
2303
+ <div class="panel">
2304
+ <div class="label">{_html.escape(T['compressed_label'].format(size=comp_size))}<span class="info">{comp_info_text}</span></div>
2305
+ <div class="image-wrap" id="comp-wrap"><img src="{comp_url}" id="comp-img" alt="compressed"/></div>
2306
+ </div>
2307
+ </div>
2308
+ <div class="overlay-view" id="overlay-view">
2309
+ <div class="overlay-label" id="overlay-label">{_html.escape(T['compressed'] + T['toggle_suffix'])} \u00b7 {comp_info_text}</div>
2310
+ <div class="overlay-wrap" id="overlay-wrap">
2311
+ <img src="{orig_url}" class="overlay-img" id="overlay-orig" alt="original" style="display:none"/>
2312
+ <img src="{comp_url}" class="overlay-img" id="overlay-comp" alt="compressed"/>
2313
+ </div>
2314
+ </div>
2315
+ <div class="slider-view" id="slider-view" style="display:none">
2316
+ <div class="slider-label">
2317
+ <span class="side">{_html.escape(T['original_label'].format(size=orig_size))}<span class="info">{orig_info_text}</span></span>
2318
+ <span class="side right">{_html.escape(T['compressed_label'].format(size=comp_size))}<span class="info">{comp_info_text}</span></span>
2319
+ </div>
2320
+ <div class="slider-wrap" id="slider-wrap">
2321
+ <img src="{comp_url}" class="slider-img" id="slider-base" alt="compressed" draggable="false"/>
2322
+ <img src="{orig_url}" class="slider-img slider-top" id="slider-top" alt="original" draggable="false"/>
2323
+ <div class="slider-handle" id="slider-handle">
2324
+ <div class="slider-handle-grip">\u2194</div>
2325
+ </div>
2326
+ </div>
2327
+ </div>
2328
+ <div class="footer" id="footer-hint">{_html.escape(T['footer_overlay'])}</div>
2329
+ <script>
2330
+ (function(){{
2331
+ var I18N = {js_i18n};
2332
+ var sideBtn = document.getElementById('btn-side');
2333
+ var overlayBtn = document.getElementById('btn-overlay');
2334
+ var sliderBtn = document.getElementById('btn-slider');
2335
+ var fitBtn = document.getElementById('btn-fit');
2336
+ var zoomBtn = document.getElementById('btn-zoom100');
2337
+ var sideView = document.getElementById('side-view');
2338
+ var overlayView = document.getElementById('overlay-view');
2339
+ var sliderView = document.getElementById('slider-view');
2340
+ var origWrap = document.getElementById('orig-wrap');
2341
+ var compWrap = document.getElementById('comp-wrap');
2342
+ var origImg = document.getElementById('orig-img');
2343
+ var compImg = document.getElementById('comp-img');
2344
+ var orig = document.getElementById('overlay-orig');
2345
+ var comp = document.getElementById('overlay-comp');
2346
+ var label = document.getElementById('overlay-label');
2347
+ var wrap = document.getElementById('overlay-wrap');
2348
+ var sliderWrap = document.getElementById('slider-wrap');
2349
+ var sliderHandle = document.getElementById('slider-handle');
2350
+ var sliderTop = document.getElementById('slider-top');
2351
+ var footer = document.getElementById('footer-hint');
2352
+ var showingOriginal = false;
2353
+ var zoomedIn = false;
2354
+ var currentMode = 'overlay';
2355
+
2356
+ function setMode(m){{
2357
+ currentMode = m;
2358
+ sideView.style.display = m === 'side' ? 'flex' : 'none';
2359
+ overlayView.style.display = m === 'overlay' ? 'flex' : 'none';
2360
+ sliderView.style.display = m === 'slider' ? 'flex' : 'none';
2361
+ sideBtn.classList.toggle('active', m === 'side');
2362
+ overlayBtn.classList.toggle('active', m === 'overlay');
2363
+ sliderBtn.classList.toggle('active', m === 'slider');
2364
+ updateFooter();
2365
+ }}
2366
+ sideBtn.addEventListener('click', function(){{ setMode('side'); }});
2367
+ overlayBtn.addEventListener('click', function(){{ setMode('overlay'); }});
2368
+ sliderBtn.addEventListener('click', function(){{ setMode('slider'); }});
2369
+
2370
+ function setZoom(mode){{
2371
+ zoomedIn = mode === '100';
2372
+ [origWrap, compWrap, wrap, sliderWrap].forEach(function(w){{ w.classList.toggle('zoom-100', zoomedIn); }});
2373
+ [origImg, compImg, orig, comp].forEach(function(img){{ img.classList.toggle('zoom-100', zoomedIn); }});
2374
+ fitBtn.classList.toggle('active', !zoomedIn);
2375
+ zoomBtn.classList.toggle('active', zoomedIn);
2376
+ updateFooter();
2377
+ // Fit and 100% modes render the image differently within slider-wrap
2378
+ // (see sliderRange below), so the handle's usable range changes too -
2379
+ // re-clamp immediately rather than waiting for the next drag/keypress,
2380
+ // or a stale --pos from the other mode can sit past the new edge
2381
+ // until the user touches the slider again.
2382
+ setSliderPos(sliderPos);
2383
+ }}
2384
+ fitBtn.addEventListener('click', function(){{ setZoom('fit'); }});
2385
+ zoomBtn.addEventListener('click', function(){{ setZoom('100'); }});
2386
+
2387
+ function updateFooter(){{
2388
+ var zoomHint = zoomedIn ? I18N.zoom_hint : '';
2389
+ var text = I18N.footer_overlay;
2390
+ if (currentMode === 'side') text = I18N.footer_side;
2391
+ else if (currentMode === 'slider') text = I18N.footer_slider;
2392
+ footer.textContent = text + zoomHint;
2393
+ }}
2394
+
2395
+ function toggleImage(){{
2396
+ if (zoomedIn) return; // clicking while panning a zoomed image shouldn't also flip it
2397
+ showingOriginal = !showingOriginal;
2398
+ orig.style.display = showingOriginal ? 'block' : 'none';
2399
+ comp.style.display = showingOriginal ? 'none' : 'block';
2400
+ label.textContent = (showingOriginal ? I18N.original : I18N.compressed) + I18N.toggle_suffix
2401
+ + ' \u00b7 ' + (showingOriginal ? I18N.orig_info : I18N.comp_info);
2402
+ }}
2403
+ wrap.addEventListener('click', toggleImage);
2404
+ document.addEventListener('keydown', function(e){{
2405
+ if (currentMode === 'overlay' && e.code === 'Space') {{
2406
+ e.preventDefault();
2407
+ toggleImage();
2408
+ }}
2409
+ }});
2410
+
2411
+ // Slider (drag-to-compare) view: slider-top (original) is clipped to its
2412
+ // left `--pos` percent via CSS clip-path, revealing slider-base
2413
+ // (compressed) underneath on the right. .slider-img spans the wrap at
2414
+ // top:0;left:0;width:100%;height:100% with no inset - the handle's
2415
+ // `left: var(--pos)` is a percent of the wrap's own width, and clip-path
2416
+ // percentages are relative to the clipped element's own box, so both
2417
+ // only land on the same on-screen position when that box IS the wrap
2418
+ // (0 inset). Giving .slider-img any padding/inset here reintroduces a
2419
+ // mismatch between where the handle line sits and where the image
2420
+ // actually splits (off by a few px away from the exact center).
2421
+ // Pointer Events unify mouse/touch/pen so one listener set drives every
2422
+ // input type; dragging is bound to the whole wrap (not just the handle)
2423
+ // for an easy-to-grab target, matching how these compare sliders usually
2424
+ // work elsewhere. Known limitation: if Max Width resize changed the
2425
+ // compressed image's pixel dimensions, 100%-zoom alignment can be
2426
+ // slightly off at the edges since each layer then sizes to its own
2427
+ // natural dimensions (the other two views make the same simplification
2428
+ // in that mode) - Fit mode is unaffected since both layers always share
2429
+ // one calculated box there.
2430
+ var sliderPos = 50;
2431
+ function clampPct(n){{ return Math.min(100, Math.max(0, n)); }}
2432
+ function sliderRange(){{
2433
+ // .slider-img always fills slider-wrap's own box (100%/100% in Fit
2434
+ // mode, or the natural-size box in 100% mode - see the comment above
2435
+ // on why --pos and clip-path stay percentages of the wrap itself).
2436
+ // But object-fit only controls how pixels are drawn *inside* that
2437
+ // box: a source image whose aspect ratio doesn't match the wrap's
2438
+ // still leaves letterboxed empty margin the handle could otherwise
2439
+ // reach into. Compute where the image is actually visible and clamp
2440
+ // to that instead of the full 0-100 wrap range.
2441
+ var rect = sliderWrap.getBoundingClientRect();
2442
+ var nw = sliderTop.naturalWidth, nh = sliderTop.naturalHeight;
2443
+ if (!rect.width || !rect.height || !nw || !nh) return {{min: 0, max: 100}};
2444
+ var renderedWidth, offsetX;
2445
+ if (sliderWrap.classList.contains('zoom-100')) {{
2446
+ // object-fit:none, top:0;left:0 - drawn at natural size, anchored
2447
+ // to the top-left corner (not centered); the wrap scrolls instead
2448
+ // of centering when the image is larger than it.
2449
+ renderedWidth = Math.min(nw, rect.width);
2450
+ offsetX = 0;
2451
+ }} else {{
2452
+ // object-fit:contain - scaled to fit and centered on both axes.
2453
+ var scale = Math.min(rect.width / nw, rect.height / nh);
2454
+ renderedWidth = nw * scale;
2455
+ offsetX = (rect.width - renderedWidth) / 2;
2456
+ }}
2457
+ return {{
2458
+ min: clampPct(offsetX / rect.width * 100),
2459
+ max: clampPct((offsetX + renderedWidth) / rect.width * 100)
2460
+ }};
2461
+ }}
2462
+ function setSliderPos(pct){{
2463
+ var range = sliderRange();
2464
+ sliderPos = Math.min(range.max, Math.max(range.min, pct));
2465
+ sliderWrap.style.setProperty('--pos', sliderPos + '%');
2466
+ }}
2467
+ function pctFromClientX(clientX){{
2468
+ var rect = sliderWrap.getBoundingClientRect();
2469
+ if (rect.width === 0) return sliderPos;
2470
+ return (clientX - rect.left) / rect.width * 100;
2471
+ }}
2472
+ var dragging = false;
2473
+ sliderWrap.addEventListener('pointerdown', function(e){{
2474
+ dragging = true;
2475
+ sliderWrap.setPointerCapture(e.pointerId);
2476
+ setSliderPos(pctFromClientX(e.clientX));
2477
+ e.preventDefault();
2478
+ }});
2479
+ sliderWrap.addEventListener('pointermove', function(e){{
2480
+ if (!dragging) return;
2481
+ setSliderPos(pctFromClientX(e.clientX));
2482
+ }});
2483
+ function endSliderDrag(e){{
2484
+ dragging = false;
2485
+ try {{ sliderWrap.releasePointerCapture(e.pointerId); }} catch (err) {{}}
2486
+ }}
2487
+ sliderWrap.addEventListener('pointerup', endSliderDrag);
2488
+ sliderWrap.addEventListener('pointercancel', endSliderDrag);
2489
+ }})();
2490
+ </script>
2491
+ </body></html>"""
2492
+ return HTMLResponse(html)
2493
+
2494
+
2495
+ @app.get("/favicon.ico")
2496
+ async def favicon():
2497
+ fav = BASE_DIR / "templates" / "favicon.ico"
2498
+ if fav.exists():
2499
+ return FileResponse(str(fav), media_type="image/x-icon")
2500
+ return Response(status_code=404)
2501
+
2502
+
2503
+ @app.get("/api/download/{ws_name}")
2504
+ async def download_zip(ws_name: str, state: AppState = Depends(get_session)):
2505
+ if not (state.workspace and state.workspace.name == ws_name):
2506
+ return JSONResponse({"error": "Invalid workspace"}, status_code=404)
2507
+
2508
+ output_dir = state.workspace / "output"
2509
+ if not output_dir.exists():
2510
+ return JSONResponse({"error": "No files to download"}, status_code=404)
2511
+
2512
+ zip_path = state.workspace / "optimized.zip"
2513
+
2514
+ def _build_zip():
2515
+ # ZipFile + glob + write are all synchronous blocking I/O — running
2516
+ # them inline in an async endpoint would freeze the whole event
2517
+ # loop for the duration of the archive build (progress polls for
2518
+ # this same session, plus every other session's image thumbnails
2519
+ # and concurrent scans, all stall out). Hand the synchronous work
2520
+ # to a thread executor and await the result.
2521
+ with ZipFile(zip_path, "w") as zf:
2522
+ for f in output_dir.rglob("*"):
2523
+ if f.is_file():
2524
+ arcname = str(f.relative_to(output_dir))
2525
+ zf.write(f, arcname)
2526
+
2527
+ # Cache: rebuild only when the archive is missing or the outputs changed
2528
+ # since it was built (output_version bumps once per completed run). A
2529
+ # repeated download of an unchanged batch — or a second click after the
2530
+ # browser's first request — then serves the existing file without paying
2531
+ # the rglob + re-compress cost again.
2532
+ if not (zip_path.exists() and state.zip_built_version == state.output_version):
2533
+ await asyncio.to_thread(_build_zip)
2534
+ state.zip_built_version = state.output_version
2535
+
2536
+ return FileResponse(
2537
+ str(zip_path),
2538
+ media_type="application/zip",
2539
+ filename="optimized_images.zip",
2540
+ )
2541
+
2542
+
2543
+ @app.get("/api/recent")
2544
+ async def get_recent(_auth: None = Depends(require_token)):
2545
+ return JSONResponse(_load_recent())
2546
+
2547
+
2548
+ @app.post("/api/recent/remove")
2549
+ async def recent_remove(data: RecentRemoveRequest, _auth: None = Depends(require_token)):
2550
+ recent = _load_recent()
2551
+ if data.key in recent and data.value in recent[data.key]:
2552
+ recent[data.key] = [p for p in recent[data.key] if p != data.value]
2553
+ _save_recent(recent)
2554
+ return JSONResponse({"ok": True})
2555
+
2556
+
2557
+ @app.post("/api/recent/clear")
2558
+ async def recent_clear(data: RecentClearRequest, _auth: None = Depends(require_token)):
2559
+ recent = _load_recent()
2560
+ if data.key in recent:
2561
+ recent[data.key] = []
2562
+ _save_recent(recent)
2563
+ return JSONResponse({"ok": True})
2564
+
2565
+
2566
+ @app.get("/api/browse-folder")
2567
+ async def browse_folder(title: str = "Select Folder", _auth: None = Depends(require_token)):
2568
+ try:
2569
+ import tkinter as tk
2570
+ from tkinter import filedialog
2571
+ except ImportError:
2572
+ return JSONResponse({"path": "", "error": "tkinter not available"})
2573
+ try:
2574
+ def _open():
2575
+ # Without DPI awareness, Windows upscales the native dialog using
2576
+ # bitmap stretching on high-DPI displays — the whole window looks
2577
+ # noticeably blurry. Declare per-monitor awareness before creating
2578
+ # any Tk widgets so the dialog renders at the native resolution.
2579
+ try:
2580
+ import ctypes
2581
+ ctypes.windll.shcore.SetProcessDpiAwareness(1)
2582
+ except Exception:
2583
+ try:
2584
+ ctypes.windll.user32.SetProcessDPIAware()
2585
+ except Exception:
2586
+ pass
2587
+ root = tk.Tk()
2588
+ root.withdraw()
2589
+ root.attributes("-topmost", True)
2590
+ # Can't make this window use Chrome's icon — it's a native Tk
2591
+ # window, not something the browser renders — but we can at
2592
+ # least use our own icon instead of the generic Tk feather.
2593
+ icon = BASE_DIR / "templates" / "favicon.ico"
2594
+ if icon.exists():
2595
+ try:
2596
+ root.iconbitmap(str(icon))
2597
+ except Exception:
2598
+ pass # e.g. .ico unsupported on non-Windows Tk builds
2599
+ root.update()
2600
+ path = filedialog.askdirectory(title=title)
2601
+ root.destroy()
2602
+ return path
2603
+ path = await asyncio.to_thread(_open)
2604
+ return JSONResponse({"path": path or ""})
2605
+ except Exception as e:
2606
+ return JSONResponse({"path": "", "error": str(e)})
2607
+
2608
+
2609
+ if sys.platform == "win32":
2610
+ import ctypes
2611
+ from ctypes import wintypes
2612
+
2613
+ def _focus_new_explorer_window(timeout: float = 3.0):
2614
+ """Best-effort: bring the folder window we just asked explorer to
2615
+ open to the foreground.
2616
+
2617
+ Two Windows behaviors work against us here:
2618
+ 1. Plain `explorer <dir>` may silently reuse an already-open window
2619
+ for that folder instead of making a new visible one, so the
2620
+ caller launches with /e,/root, (see reveal_in_explorer) which
2621
+ always spawns a fresh CabinetWClass window.
2622
+ 2. Foreground lock: this server process sits behind the browser, and
2623
+ Windows refuses to let a window created by a background process
2624
+ steal focus — it opens behind the browser or just flashes in the
2625
+ taskbar. Attaching our input state to the current foreground
2626
+ thread before SetForegroundWindow is the documented workaround.
2627
+
2628
+ Runs in a worker thread (it polls/sleeps) and is purely cosmetic —
2629
+ the window is open regardless of whether focusing succeeds.
2630
+ """
2631
+ try:
2632
+ user32 = ctypes.windll.user32
2633
+ _EnumWindowsProc = ctypes.WINFUNCTYPE(wintypes.BOOL, wintypes.HWND, wintypes.LPARAM)
2634
+
2635
+ def cabinet_windows() -> list:
2636
+ found = []
2637
+
2638
+ def _cb(hwnd, _lparam):
2639
+ buf = ctypes.create_unicode_buffer(64)
2640
+ user32.GetClassNameW(hwnd, buf, 64)
2641
+ # CabinetWClass = an Explorer folder window (the shell
2642
+ # taskbar/desktop and dialogs use other classes).
2643
+ if buf.value == "CabinetWClass":
2644
+ found.append(hwnd)
2645
+ return True
2646
+
2647
+ user32.EnumWindows(_EnumWindowsProc(_cb), 0)
2648
+ return found
2649
+
2650
+ before = set(cabinet_windows())
2651
+ deadline = time.monotonic() + timeout
2652
+ new_hwnd = None
2653
+ while new_hwnd is None and time.monotonic() < deadline:
2654
+ time.sleep(0.1)
2655
+ for hwnd in cabinet_windows():
2656
+ if hwnd not in before:
2657
+ new_hwnd = hwnd
2658
+ break
2659
+ if new_hwnd is None:
2660
+ return # window never appeared (or appeared too late) — give up
2661
+
2662
+ fg_hwnd = user32.GetForegroundWindow()
2663
+ fg_tid = user32.GetWindowThreadProcessId(fg_hwnd, None) if fg_hwnd else 0
2664
+ tgt_tid = user32.GetWindowThreadProcessId(new_hwnd, None)
2665
+ attached = bool(
2666
+ fg_tid and tgt_tid and fg_tid != tgt_tid
2667
+ and user32.AttachThreadInput(fg_tid, tgt_tid, True)
2668
+ )
2669
+ try:
2670
+ user32.ShowWindow(new_hwnd, 9) # SW_RESTORE, in case it's minimized
2671
+ user32.SetForegroundWindow(new_hwnd)
2672
+ finally:
2673
+ if attached:
2674
+ user32.AttachThreadInput(fg_tid, tgt_tid, False)
2675
+ except Exception:
2676
+ pass # cosmetic only — never break the reveal itself
2677
+
2678
+
2679
+ @app.post("/api/reveal")
2680
+ async def reveal_in_explorer(
2681
+ data: RevealRequest, state: AppState = Depends(get_session), _auth: None = Depends(require_token)
2682
+ ):
2683
+ """Open the OS file explorer — either the run's output folder itself
2684
+ (empty path) or with a specific output file selected.
2685
+
2686
+ Folder mode (data.path empty): opens state.output_dir, the persistent
2687
+ output folder _process_files recorded for this run. The target comes
2688
+ entirely from server-side state, so there is nothing client-supplied
2689
+ to validate. This backs the single "Reveal Output Folder" button in
2690
+ the Results bar (one output folder per run → one button, not one per
2691
+ image).
2692
+
2693
+ File mode: data.path must exactly match one of *this session's*
2694
+ recorded final_output_path values (set on results only when a
2695
+ persistent output_dir was used — see process_one). Without that
2696
+ check, this endpoint would be an arbitrary "launch explorer at any
2697
+ path on disk" oracle driven entirely by client-supplied input;
2698
+ requiring it to be a path this app itself just wrote, for this
2699
+ session, keeps it scoped to "reveal something you just compressed"
2700
+ and nothing else.
2701
+ """
2702
+ if not data.path:
2703
+ if not state.output_dir:
2704
+ return JSONResponse({"error": "No output folder for this session"}, status_code=400)
2705
+ target = Path(state.output_dir)
2706
+ select_file = False
2707
+ else:
2708
+ requested = str(Path(data.path))
2709
+ if not any(r.get("final_output_path") == requested for r in state.results):
2710
+ return JSONResponse({"error": "Not a known output file for this session"}, status_code=400)
2711
+ target = Path(requested)
2712
+ select_file = True
2713
+
2714
+ if not target.exists():
2715
+ return JSONResponse(
2716
+ {"error": "File no longer exists on disk" if select_file else "Folder no longer exists on disk"},
2717
+ status_code=404,
2718
+ )
2719
+
2720
+ try:
2721
+ if select_file:
2722
+ if sys.platform == "win32":
2723
+ # /select, (comma, no space) + the path as one argument is
2724
+ # explorer.exe's documented syntax for "open the containing
2725
+ # folder with this file highlighted". explorer.exe routinely
2726
+ # returns a non-zero exit code even on success, so this is
2727
+ # fire-and-forget rather than awaited/checked.
2728
+ subprocess.Popen(["explorer", f"/select,{target}"])
2729
+ elif sys.platform == "darwin":
2730
+ subprocess.Popen(["open", "-R", str(target)])
2731
+ else:
2732
+ # No cross-desktop-environment equivalent of "select this
2733
+ # file" on Linux — best effort is opening its containing
2734
+ # folder.
2735
+ subprocess.Popen(["xdg-open", str(target.parent)])
2736
+ else:
2737
+ if sys.platform == "win32":
2738
+ # /e,/root, forces a fresh folder window — a bare
2739
+ # `explorer <dir>` may silently reuse an already-open one.
2740
+ subprocess.Popen(["explorer", f"/e,/root,{target}"])
2741
+ # Then pull that window to the front: this process sits
2742
+ # behind the browser, so Windows' foreground lock would
2743
+ # otherwise leave it hidden (see _focus_new_explorer_window).
2744
+ # Fire-and-forget off the event loop — the response doesn't
2745
+ # need to wait for the animation.
2746
+ asyncio.create_task(asyncio.to_thread(_focus_new_explorer_window))
2747
+ elif sys.platform == "darwin":
2748
+ subprocess.Popen(["open", str(target)])
2749
+ else:
2750
+ subprocess.Popen(["xdg-open", str(target)])
2751
+ except OSError as e:
2752
+ return JSONResponse({"error": f"Could not open file explorer: {e}"}, status_code=500)
2753
+
2754
+ return JSONResponse({"success": True})
2755
+
2756
+
2757
+ @app.get("/api/state")
2758
+ async def get_state(state: AppState = Depends(get_session)):
2759
+ return JSONResponse({
2760
+ "files": state.files,
2761
+ "results": state.results,
2762
+ "input_dir": state.input_dir,
2763
+ "is_running": state.is_running,
2764
+ "current": state.current,
2765
+ "total": state.total,
2766
+ "paused": state.paused,
2767
+ # Explicit, so the frontend doesn't have to derive it by parsing
2768
+ # files[0].thumbnail — that string starts "" for files rebuilt on
2769
+ # resume and only fills in once _backfill_resume_thumbnails'
2770
+ # background task gets to each one, which silently broke
2771
+ # compare/preview URLs for the whole session (not just the still-
2772
+ # blank files) until this field existed. See STATE.wsName in
2773
+ # index.html.
2774
+ "ws_name": state.workspace.name if state.workspace else "",
2775
+ })
2776
+
2777
+
2778
+ @app.get("/api/batch-state")
2779
+ async def get_batch_state(output_dir: Optional[str] = None, state: AppState = Depends(get_session)):
2780
+ """Return whether there's an unfinished batch that can be resumed.
2781
+ Called on page load so the frontend can show a 'Resume?' prompt.
2782
+
2783
+ Batch state is stored one file per output_dir (see _batch_state_file),
2784
+ so this never mixes results from an unrelated batch:
2785
+ - output_dir given: report on that specific batch only.
2786
+ - output_dir omitted (the page-load case, before the user has picked a
2787
+ folder): report the most recently updated batch that still has
2788
+ pending/failed files, out of everything currently on disk. Every
2789
+ candidate here is a real, currently-unfinished batch — finishing an
2790
+ unrelated batch elsewhere can no longer make this list wrong, since
2791
+ that batch's own file is the only one touched when it completes.
2792
+ """
2793
+ if output_dir:
2794
+ bs = _load_batch_state(output_dir)
2795
+ else:
2796
+ candidates = _list_unfinished_batch_states()
2797
+ bs = candidates[0] if candidates else None
2798
+ if bs is None:
2799
+ return JSONResponse({"has_batch": False})
2800
+ total = len(bs.get("files", []))
2801
+ done = sum(1 for f in bs.get("files", []) if f["status"] == "done")
2802
+ failed = sum(1 for f in bs.get("files", []) if f["status"] == "failed")
2803
+ pending = total - done - failed
2804
+ return JSONResponse({
2805
+ "has_batch": True,
2806
+ "total": total,
2807
+ "done": done,
2808
+ "failed": failed,
2809
+ "pending": pending,
2810
+ "output_dir": bs.get("output_dir", ""),
2811
+ "output_format": bs.get("output_format", "png"),
2812
+ "quality": bs.get("quality", "medium"),
2813
+ "compression_mode": bs.get("compression_mode", "standard"),
2814
+ "created_at": bs.get("created_at", ""),
2815
+ })
2816
+
2817
+
2818
+ # Keys that require a server restart to take effect. Changing them via
2819
+ # PUT /api/settings succeeds (the new value is persisted to config.json)
2820
+ # but the response flags requires_restart so the UI can tell the user.
2821
+ _RESTART_REQUIRED_KEYS = {"host", "port", "concurrent_workers", "thumbnail_workers"}
2822
+
2823
+
2824
+ @app.get("/api/settings")
2825
+ async def get_settings():
2826
+ """Return the current config (merged with defaults) for the settings panel."""
2827
+ cfg = _load_app_config()
2828
+ return JSONResponse({
2829
+ "settings": cfg,
2830
+ "defaults": dict(DEFAULT_CONFIG),
2831
+ })
2832
+
2833
+
2834
+ @app.put("/api/settings")
2835
+ async def put_settings(
2836
+ body: Request,
2837
+ _auth: None = Depends(require_token),
2838
+ ):
2839
+ """Accept a partial or full config update, validate, and persist to config.json.
2840
+ Returns which keys require a restart to take effect."""
2841
+ try:
2842
+ data = await body.json()
2843
+ except Exception:
2844
+ return JSONResponse({"error": "Invalid JSON body"}, status_code=400)
2845
+
2846
+ if not isinstance(data, dict):
2847
+ return JSONResponse({"error": "Request body must be a JSON object"}, status_code=400)
2848
+
2849
+ # Load current config as the base, then overlay the submitted changes
2850
+ cfg = _load_app_config()
2851
+ requires_restart = []
2852
+
2853
+ for key, value in data.items():
2854
+ if key not in DEFAULT_CONFIG:
2855
+ return JSONResponse(
2856
+ {"error": f"Unknown setting: {key!r}. Known: {list(DEFAULT_CONFIG.keys())}"},
2857
+ status_code=400,
2858
+ )
2859
+ # Type/value validation per key
2860
+ if key == "port":
2861
+ try:
2862
+ port = int(value)
2863
+ if not (1 <= port <= 65535):
2864
+ raise ValueError()
2865
+ except (TypeError, ValueError):
2866
+ return JSONResponse(
2867
+ {"error": f"Invalid port: {value!r}. Must be an integer 1-65535."},
2868
+ status_code=400,
2869
+ )
2870
+ cfg["port"] = port
2871
+ elif key in ("concurrent_workers", "thumbnail_workers"):
2872
+ try:
2873
+ n = int(value)
2874
+ if n < 1:
2875
+ raise ValueError()
2876
+ except (TypeError, ValueError):
2877
+ return JSONResponse(
2878
+ {"error": f"Invalid {key}: {value!r}. Must be a positive integer."},
2879
+ status_code=400,
2880
+ )
2881
+ cfg[key] = n
2882
+ elif key == "workspace_cleanup_delay":
2883
+ try:
2884
+ d = float(value)
2885
+ if d < 0:
2886
+ raise ValueError()
2887
+ except (TypeError, ValueError):
2888
+ return JSONResponse(
2889
+ {"error": f"Invalid {key}: {value!r}. Must be a non-negative number."},
2890
+ status_code=400,
2891
+ )
2892
+ cfg[key] = d
2893
+ elif key == "session_idle_timeout_hours":
2894
+ try:
2895
+ h = float(value)
2896
+ if h < 0:
2897
+ raise ValueError()
2898
+ except (TypeError, ValueError):
2899
+ return JSONResponse(
2900
+ {"error": f"Invalid {key}: {value!r}. Must be a non-negative number."},
2901
+ status_code=400,
2902
+ )
2903
+ cfg[key] = h
2904
+ elif key == "host":
2905
+ if not isinstance(value, str) or not value.strip():
2906
+ return JSONResponse(
2907
+ {"error": f"Invalid host: {value!r}. Must be a non-empty string."},
2908
+ status_code=400,
2909
+ )
2910
+ cfg[key] = value.strip()
2911
+ else:
2912
+ cfg[key] = value
2913
+
2914
+ if key in _RESTART_REQUIRED_KEYS:
2915
+ requires_restart.append(key)
2916
+
2917
+ # Persist to config.json
2918
+ try:
2919
+ _config_file().write_text(
2920
+ json.dumps(cfg, indent=2, ensure_ascii=False),
2921
+ encoding="utf-8",
2922
+ )
2923
+ except OSError as e:
2924
+ return JSONResponse(
2925
+ {"error": f"Failed to write config.json: {e}"},
2926
+ status_code=500,
2927
+ )
2928
+
2929
+ return JSONResponse({
2930
+ "ok": True,
2931
+ "settings": cfg,
2932
+ "requires_restart": requires_restart,
2933
+ })
2934
+
2935
+
2936
+ @app.post("/api/reset")
2937
+ async def reset_session(state: AppState = Depends(get_session), _auth: None = Depends(require_token)):
2938
+ """Clear this session's server-side state (the UI Reset button used to
2939
+ only wipe the page, leaving files/results alive server-side — a page
2940
+ refresh with /api/state restore would resurrect them). The workspace is
2941
+ deleted with the same grace period as a workspace swap."""
2942
+ if state.is_running:
2943
+ return JSONResponse({"error": "Optimization in progress, please wait"}, status_code=400)
2944
+ if state.scan_running:
2945
+ return JSONResponse({"error": "A scan is already in progress, please wait"}, status_code=400)
2946
+ if state.workspace:
2947
+ asyncio.create_task(_delayed_rmtree(state.workspace))
2948
+ state.workspace = None
2949
+ state.reset()
2950
+ return JSONResponse({"ok": True})
2951
+
2952
+
2953
+ # ---------------------------------------------------------------------------
2954
+ # Watch mode
2955
+ # ---------------------------------------------------------------------------
2956
+
2957
+ def _watch_output_conflicts_with_input(directory: Path, output_dir: Path, recursive: bool) -> bool:
2958
+ """True if writing optimized output into output_dir would land back
2959
+ inside the tree Watch mode is scanning — which would make the watcher
2960
+ detect its own output as a new/changed file and reprocess it forever
2961
+ (empirically confirmed: a single dropped-in file gets re-picked-up on
2962
+ every poll interval indefinitely once this happens, silently burning
2963
+ CPU and rewriting the file over and over — see CHANGELOG).
2964
+
2965
+ - output_dir == directory: always a conflict, no matter recursive —
2966
+ the top level is always scanned.
2967
+ - output_dir inside directory, recursive=True: a conflict — the
2968
+ recursive walk would descend into it too.
2969
+ - output_dir inside directory, recursive=False: fine — a non-recursive
2970
+ scan only lists directory's immediate children, so a nested output
2971
+ folder's contents are never re-scanned.
2972
+ """
2973
+ d = directory.resolve()
2974
+ o = output_dir.resolve()
2975
+ if o == d:
2976
+ return True
2977
+ if recursive:
2978
+ try:
2979
+ o.relative_to(d)
2980
+ return True
2981
+ except ValueError:
2982
+ return False
2983
+ return False
2984
+
2985
+
2986
+ async def _watch_loop(state: AppState, req: WatchRequest):
2987
+ """Background task for Watch mode — monitors a directory and auto-
2988
+ optimizes every new/changed image using the same compression pipeline
2989
+ as the batch optimizer. Each file is independent: an error on one
2990
+ doesn't stop the rest (logged to state.watch_errors instead)."""
2991
+ if optimizer is None:
2992
+ state.watch_logs.append("[Error] Optimizer not initialized")
2993
+ state.watch_running = False
2994
+ return
2995
+
2996
+ directory = Path(req.directory)
2997
+ output_dir = Path(req.output_dir) if req.output_dir else None
2998
+
2999
+ quality_map = {"high": 85, "medium": 75, "low": 60}
3000
+ used_names: set[str] = set()
3001
+ # rel_path -> the output file actually written for it, so a detected
3002
+ # rename can find and remove the *old* name's output. A plain set
3003
+ # (used_names) only tells us a filename is taken, not which source it
3004
+ # came from, and the collision guard can shift the actual filename
3005
+ # away from the naive with_suffix() guess (e.g. "_2.png") — this dict
3006
+ # tracks the real path so cleanup targets the right file.
3007
+ output_path_for: dict[str, Path] = {}
3008
+
3009
+ async def on_change(rel_path: str, abs_path: Path, renamed_from: Optional[str] = None):
3010
+ if optimizer is None:
3011
+ return
3012
+ try:
3013
+ if output_dir:
3014
+ out_path = output_dir / Path(rel_path).with_suffix(f".{req.output_format}")
3015
+ out_path.parent.mkdir(parents=True, exist_ok=True)
3016
+ # Collision guard: same filename from different subdirs
3017
+ key = str(out_path).lower()
3018
+ if key in used_names:
3019
+ n = 2
3020
+ while key in used_names:
3021
+ out_path = output_dir / Path(rel_path).with_name(
3022
+ f"{Path(rel_path).stem}_{n}.{req.output_format}"
3023
+ )
3024
+ key = str(out_path).lower()
3025
+ n += 1
3026
+ used_names.add(key)
3027
+ else:
3028
+ return
3029
+
3030
+ # Rename cleanup: FolderWatcher only sets renamed_from when a
3031
+ # path vanished and this one appeared in the very same scan
3032
+ # with an identical (mtime, size) — a same-content rename, not
3033
+ # an unrelated delete. Remove the old name's output now that a
3034
+ # fresh one is about to be written for the new name, so the
3035
+ # stale copy doesn't sit around forever. A file that's simply
3036
+ # deleted (renamed_from is None for everyone, always) never
3037
+ # reaches this branch — its output is left untouched, since
3038
+ # plenty of people delete the original and keep only the
3039
+ # compressed result.
3040
+ if renamed_from is not None:
3041
+ old_output = output_path_for.pop(renamed_from, None)
3042
+ if old_output is not None and old_output != out_path:
3043
+ try:
3044
+ if old_output.exists():
3045
+ old_output.unlink()
3046
+ used_names.discard(str(old_output).lower())
3047
+ state.watch_logs.append(
3048
+ f" Renamed: {renamed_from} -> {rel_path} (removed old output {old_output.name})"
3049
+ )
3050
+ except OSError as e:
3051
+ state.watch_logs.append(
3052
+ f" WARN: couldn't remove old output for renamed file {renamed_from!r}: {e}"
3053
+ )
3054
+
3055
+ state.watch_logs.append(f"Detected: {rel_path}")
3056
+
3057
+ q = quality_map.get(req.quality, 75)
3058
+ if req.compression_mode in ("lossless", "resize_only"):
3059
+ q = 95
3060
+
3061
+ result = await optimizer.optimize_png(
3062
+ input_path=abs_path,
3063
+ output_path=out_path,
3064
+ quality=req.quality,
3065
+ max_width=req.max_width,
3066
+ compression_mode=req.compression_mode,
3067
+ protected_colors=req.protected_colors,
3068
+ dithering=req.dithering,
3069
+ output_format=req.output_format,
3070
+ keep_exif=req.keep_exif,
3071
+ )
3072
+
3073
+ state.watch_processed += 1
3074
+ if result.get("success"):
3075
+ output_path_for[rel_path] = out_path
3076
+ savings = result["original_size"] - result["compressed_size"]
3077
+ pct = round(savings / result["original_size"] * 100, 1) if result["original_size"] > 0 else 0
3078
+ state.watch_logs.append(
3079
+ f" OK {rel_path}: {_fmt_size(result['original_size'])} -> "
3080
+ f"{_fmt_size(result['compressed_size'])} (saved {pct}%)"
3081
+ )
3082
+ else:
3083
+ state.watch_errors += 1
3084
+ state.watch_logs.append(f" FAIL {rel_path}: {result.get('error', 'unknown')}")
3085
+ except Exception as e:
3086
+ state.watch_errors += 1
3087
+ state.watch_logs.append(f" ERROR {rel_path}: {e}")
3088
+
3089
+ watcher = FolderWatcher(
3090
+ directory=directory,
3091
+ recursive=req.recursive,
3092
+ process_existing=req.process_existing,
3093
+ on_change=on_change,
3094
+ )
3095
+ state.watch_watcher = watcher
3096
+ try:
3097
+ await watcher.run()
3098
+ except asyncio.CancelledError:
3099
+ pass
3100
+ finally:
3101
+ state.watch_running = False
3102
+ state.watch_logs.append("Watch mode stopped")
3103
+
3104
+
3105
+ @app.post("/api/watch/start")
3106
+ async def watch_start(
3107
+ data: WatchRequest,
3108
+ state: AppState = Depends(get_session),
3109
+ _auth: None = Depends(require_token),
3110
+ ):
3111
+ """Start watching a directory for image changes and auto-optimize
3112
+ every new/changed file into output_dir. Uses the same compression
3113
+ pipeline as the batch optimizer. Watch and batch-optimize are
3114
+ mutually exclusive per session — both write files and mutate
3115
+ overlapping state, so running them concurrently would be unsafe."""
3116
+ if optimizer is None:
3117
+ return JSONResponse({"error": "Optimizer not initialized"}, status_code=503)
3118
+ if state.is_running:
3119
+ return JSONResponse({"error": "Optimization in progress, please wait"}, status_code=400)
3120
+ if state.scan_running:
3121
+ return JSONResponse({"error": "A scan is in progress, please wait"}, status_code=400)
3122
+ if state.watch_running:
3123
+ return JSONResponse({"error": "Watch mode is already running"}, status_code=400)
3124
+
3125
+ directory = Path(data.directory)
3126
+ if not directory.exists() or not directory.is_dir():
3127
+ return JSONResponse({"error": "Directory does not exist"}, status_code=400)
3128
+ if data.output_dir:
3129
+ od = Path(data.output_dir)
3130
+ if not od.exists():
3131
+ return JSONResponse({"error": "Output directory does not exist"}, status_code=400)
3132
+ if _watch_output_conflicts_with_input(directory, od, data.recursive):
3133
+ return JSONResponse({
3134
+ "error": (
3135
+ "output_dir can't be the watched directory itself, or a "
3136
+ "subfolder of it while watching recursively — writing "
3137
+ "optimized output back into the watched tree makes Watch "
3138
+ "mode detect its own output as a new/changed file and "
3139
+ "reprocess it forever. Pick an output folder outside "
3140
+ "the watched directory (or turn off recursive watching "
3141
+ "if the output folder must live inside it)."
3142
+ ),
3143
+ }, status_code=400)
3144
+
3145
+ err = _validate_optimize_settings(
3146
+ data.quality, data.output_format, data.compression_mode, data.max_width, data.protected_colors,
3147
+ )
3148
+ if err:
3149
+ return JSONResponse({"error": err}, status_code=400)
3150
+
3151
+ warning = None
3152
+ if (data.output_format, data.compression_mode) not in optimizer.available_modes():
3153
+ warning = (
3154
+ f"Format {data.output_format!r} in {data.compression_mode} mode isn't available — "
3155
+ f"output may fail. Check the health indicator for missing binaries."
3156
+ )
3157
+
3158
+ state.watch_running = True
3159
+ state.watch_dir = str(directory.resolve())
3160
+ state.watch_output_dir = data.output_dir or ""
3161
+ state.watch_processed = 0
3162
+ state.watch_errors = 0
3163
+ state.watch_logs = []
3164
+ state.watch_task = asyncio.create_task(_watch_loop(state, data))
3165
+
3166
+ return JSONResponse({
3167
+ "ok": True,
3168
+ "watch_running": True,
3169
+ "watch_dir": state.watch_dir,
3170
+ "warning": warning,
3171
+ })
3172
+
3173
+
3174
+ async def _stop_watch(state: "AppState") -> None:
3175
+ """Cancel Watch Mode for one session and clear its fields. Shared by
3176
+ the explicit /api/watch/stop endpoint and the stale-session sweep
3177
+ (_sweep_stale_sessions_once) so there is exactly one place that knows
3178
+ how to tear a watch task down. Safe to call when watch isn't running —
3179
+ every step below is a no-op in that case."""
3180
+ if state.watch_watcher:
3181
+ state.watch_watcher.stop()
3182
+ if state.watch_task:
3183
+ state.watch_task.cancel()
3184
+ try:
3185
+ await state.watch_task
3186
+ except asyncio.CancelledError:
3187
+ pass
3188
+ state.watch_running = False
3189
+ state.watch_watcher = None
3190
+ state.watch_task = None
3191
+
3192
+
3193
+ @app.post("/api/watch/stop")
3194
+ async def watch_stop(
3195
+ state: AppState = Depends(get_session),
3196
+ _auth: None = Depends(require_token),
3197
+ ):
3198
+ """Stop watch mode. Cooperative: the watcher finishes its current
3199
+ poll sleep, then exits. Already-queued file events are lost (watch
3200
+ is meant to be persistent, not transactional)."""
3201
+ if not state.watch_running:
3202
+ return JSONResponse({"error": "Watch mode is not running"}, status_code=400)
3203
+ await _stop_watch(state)
3204
+ return JSONResponse({"ok": True})
3205
+
3206
+
3207
+ @app.get("/api/watch/status")
3208
+ async def watch_status(state: AppState = Depends(get_session)):
3209
+ return JSONResponse({
3210
+ "running": state.watch_running,
3211
+ "dir": state.watch_dir,
3212
+ "output_dir": state.watch_output_dir,
3213
+ "processed": state.watch_processed,
3214
+ "errors": state.watch_errors,
3215
+ "logs": state.watch_logs,
3216
+ })
3217
+
3218
+
3219
+ @app.get("/api/watch/events")
3220
+ async def watch_events(request: Request, state: AppState = Depends(get_session)):
3221
+ """SSE transport for watch mode — mirrors the batch /api/events
3222
+ pattern. Emits `watch_result` (one per processed file), `watch_log`
3223
+ (status messages), and `watch_status` (periodic counters). A client
3224
+ that drops and reconnects gets the full current state via the first
3225
+ `watch_status` event, then incremental updates from there."""
3226
+ log_cursor = 0
3227
+
3228
+ async def event_stream():
3229
+ nonlocal log_cursor
3230
+ last_emit = time.time()
3231
+
3232
+ yield _sse_format("watch_status", {
3233
+ "running": state.watch_running,
3234
+ "processed": state.watch_processed,
3235
+ "errors": state.watch_errors,
3236
+ }, None)
3237
+
3238
+ while True:
3239
+ for line in state.watch_logs[log_cursor:]:
3240
+ log_cursor += 1
3241
+ yield _sse_format("watch_log", {"line": line}, None)
3242
+ last_emit = time.time()
3243
+
3244
+ if not state.watch_running:
3245
+ await asyncio.sleep(0.05)
3246
+ for line in state.watch_logs[log_cursor:]:
3247
+ log_cursor += 1
3248
+ yield _sse_format("watch_log", {"line": line}, None)
3249
+ yield _sse_format("watch_status", {
3250
+ "running": False,
3251
+ "processed": state.watch_processed,
3252
+ "errors": state.watch_errors,
3253
+ }, None)
3254
+ return
3255
+
3256
+ if await request.is_disconnected():
3257
+ return
3258
+
3259
+ if time.time() - last_emit > 5:
3260
+ yield ": keepalive\n\n"
3261
+ last_emit = time.time()
3262
+
3263
+ await asyncio.sleep(0.5)
3264
+
3265
+ return StreamingResponse(
3266
+ event_stream(),
3267
+ media_type="text/event-stream",
3268
+ headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no", "Connection": "keep-alive"},
3269
+ )
3270
+
3271
+
3272
+ def _matches_globs(rel_path: str, patterns: List[str]) -> bool:
3273
+ """True if rel_path (POSIX-style, relative to --source) matches any glob.
3274
+
3275
+ A pattern without "/" is matched against the file name only, so it
3276
+ applies at any depth ("*.bak" hits sub/dir/a.bak). A pattern containing
3277
+ "/" is matched against the whole relative path ("drafts/*" or
3278
+ "icons/*.png"). Matching is case-insensitive on every platform, and "*"
3279
+ crosses "/" (plain fnmatch semantics), so "drafts/*" also covers
3280
+ "drafts/old/a.png". Backslashes in a pattern are read as "/" so a
3281
+ Windows-style "sub\\*.png" works too. Empty patterns are ignored."""
3282
+ rel = rel_path.lower()
3283
+ name = rel.rsplit("/", 1)[-1]
3284
+ for raw in patterns:
3285
+ pat = raw.strip().replace("\\", "/").lower()
3286
+ if not pat:
3287
+ continue
3288
+ if fnmatch.fnmatchcase(rel if "/" in pat else name, pat):
3289
+ return True
3290
+ return False
3291
+
3292
+
3293
+ _CLI_SUCCESS_STATUSES = ("compressed", "cached", "kept_original")
3294
+
3295
+
3296
+ def _build_cli_report(files: list) -> dict:
3297
+ """Machine-readable result of a CLI run (--json). `files` holds one record
3298
+ per scanned file; statuses are mutually exclusive: compressed, cached,
3299
+ kept_original (growth-guard fallback), excluded, failed. Size totals and
3300
+ saved_percent cover the successful statuses only. `total` counts every
3301
+ scanned file, excluded ones included."""
3302
+ counts = {"compressed": 0, "cached": 0, "excluded": 0, "failed": 0, "kept_original": 0}
3303
+ orig = comp = 0
3304
+ for f in files:
3305
+ counts[f["status"]] += 1
3306
+ if f["status"] in _CLI_SUCCESS_STATUSES:
3307
+ orig += f["original_size"]
3308
+ comp += f["compressed_size"]
3309
+ return {
3310
+ "files": files,
3311
+ "summary": {
3312
+ "total": len(files),
3313
+ "compressed": counts["compressed"],
3314
+ "cached": counts["cached"],
3315
+ "excluded": counts["excluded"],
3316
+ "failed": counts["failed"],
3317
+ "kept_original": counts["kept_original"],
3318
+ "original_size": orig,
3319
+ "compressed_size": comp,
3320
+ "saved_percent": round((1 - comp / orig) * 100, 1) if orig > 0 else 0,
3321
+ },
3322
+ }
3323
+
3324
+
3325
+ async def _run_cli(args, optimizer_instance: Optional["Optimizer"] = None) -> int:
3326
+ """Headless batch run: no web server, no browser. Scans --source, runs
3327
+ every image through the exact same optimizer.optimize_png pipeline the
3328
+ web UI and Watch Mode use (so a CLI run behaves identically to a batch
3329
+ run started from the browser with the same settings — no separate
3330
+ "CLI version" of the compression logic to drift out of sync), and exits
3331
+ with a process exit code (0 if everything succeeded, 1 if anything
3332
+ failed) so this composes into scripts/CI.
3333
+
3334
+ Deliberately does not implement --skip-existing: that feature depends
3335
+ on the per-output-dir settings-fingerprint file the web/watch paths
3336
+ already maintain (see skip_existing in _process_files). Instead,
3337
+ --cache-dir enables a content-hash cache that does not depend on the
3338
+ output directory at all (see image_optimizer/cache.py); without it,
3339
+ every CLI run recompresses everything in --source.
3340
+
3341
+ With --json the final report is one JSON object on stdout and every
3342
+ human-readable line (progress, summary, warnings) goes to stderr, so
3343
+ stdout can be piped straight into a parser. Argument/setup errors
3344
+ (exit 1 before any file is looked at) print only to stderr.
3345
+ """
3346
+ as_json = bool(getattr(args, "json", False))
3347
+ log_stream = sys.stderr if as_json else sys.stdout
3348
+
3349
+ def log(*parts) -> None:
3350
+ print(*parts, file=log_stream)
3351
+
3352
+ def emit_report(files: list) -> None:
3353
+ if as_json:
3354
+ # ensure_ascii (the default) keeps stdout valid on any console
3355
+ # encoding even when file names are not ASCII.
3356
+ print(json.dumps(_build_cli_report(files), indent=2))
3357
+ sys.stdout.flush()
3358
+
3359
+ source = Path(args.source).resolve()
3360
+ if not source.exists() or not source.is_dir():
3361
+ print(f"[Error] --source is not a directory: {source}", file=sys.stderr)
3362
+ return 1
3363
+ if not args.output:
3364
+ print("[Error] --output is required when using --source", file=sys.stderr)
3365
+ return 1
3366
+ output_dir = Path(args.output).resolve()
3367
+ cache_dir_arg = getattr(args, "cache_dir", None)
3368
+ cache_max_mb = getattr(args, "cache_max_size_mb", DEFAULT_CACHE_MAX_MB)
3369
+ if cache_dir_arg and cache_max_mb < 0:
3370
+ print("[Error] --cache-max-size-mb must be >= 0 (0 = unlimited)", file=sys.stderr)
3371
+ return 1
3372
+ if cache_dir_arg is None and cache_max_mb != DEFAULT_CACHE_MAX_MB:
3373
+ # Same default as the argparse flag, so passing the flag on its own is
3374
+ # detectable without a sentinel; an explicit value equal to the
3375
+ # default stays silent, which is the only ambiguous case.
3376
+ print("[Hint] --cache-max-size-mb has no effect without --cache-dir", file=sys.stderr)
3377
+
3378
+ protected_colors = (
3379
+ [c.strip() for c in args.protect_colors.split(",") if c.strip()]
3380
+ if args.protect_colors else []
3381
+ )
3382
+ err = _validate_optimize_settings(
3383
+ args.quality, args.format, args.mode, args.max_width, protected_colors,
3384
+ )
3385
+ if err:
3386
+ print(f"[Error] {err}", file=sys.stderr)
3387
+ return 1
3388
+
3389
+ scanned = _scan_images(source, recursive=args.recursive)
3390
+ if not scanned:
3391
+ log(f"[CLI] No supported images found in {source}")
3392
+ emit_report([])
3393
+ return 0
3394
+
3395
+ # --include is a whitelist; --exclude is applied after it and always
3396
+ # wins when both match. Excluded files are neither compressed nor
3397
+ # counted as failures.
3398
+ include = getattr(args, "include", None) or []
3399
+ exclude = getattr(args, "exclude", None) or []
3400
+ images = []
3401
+ # One record per scanned file, filled in as results arrive; reported in
3402
+ # scan order.
3403
+ records: dict = {}
3404
+ for p in scanned:
3405
+ rel_posix = p.relative_to(source).as_posix()
3406
+ if (include and not _matches_globs(rel_posix, include)) or _matches_globs(rel_posix, exclude):
3407
+ try:
3408
+ excluded_size = p.stat().st_size
3409
+ except OSError:
3410
+ excluded_size = None
3411
+ records[p] = {
3412
+ "rel": rel_posix, "output_name": None, "original_size": excluded_size,
3413
+ "compressed_size": None, "status": "excluded", "error": None,
3414
+ }
3415
+ continue
3416
+ images.append(p)
3417
+ n_excluded = len(scanned) - len(images)
3418
+ if not images:
3419
+ log(f"[CLI] No images left after --include/--exclude filtering ({n_excluded} excluded)")
3420
+ emit_report([records[p] for p in scanned])
3421
+ return 0
3422
+
3423
+ cache: Optional[ContentCache] = None
3424
+ if cache_dir_arg:
3425
+ cache_dir = Path(cache_dir_arg).resolve()
3426
+
3427
+ # normcase: Windows paths are case-insensitive filesystem-wise but
3428
+ # Path comparison is not before Python 3.12, so "C:\Src" and
3429
+ # "C:\src" would otherwise slip through the containment checks and
3430
+ # the scan would pick the cache up as input on the next run.
3431
+ cache_dir_nc = os.path.normcase(str(cache_dir))
3432
+ cache_parents_nc = {os.path.normcase(str(p)) for p in cache_dir.parents}
3433
+
3434
+ def _cache_dir_inside(root: Path) -> bool:
3435
+ root_nc = os.path.normcase(str(root))
3436
+ return cache_dir_nc == root_nc or root_nc in cache_parents_nc
3437
+
3438
+ if _cache_dir_inside(source):
3439
+ # The scan would pick the cached images up as new sources.
3440
+ print("[Error] --cache-dir must not be inside --source", file=sys.stderr)
3441
+ return 1
3442
+ if _cache_dir_inside(output_dir):
3443
+ # Less fatal than --source, but the key-named cache entries would
3444
+ # land in the deliverable output directory and vanish when LRU
3445
+ # evicts them.
3446
+ print("[Error] --cache-dir must not be inside --output", file=sys.stderr)
3447
+ return 1
3448
+ if args.format not in CACHEABLE_FORMATS:
3449
+ # Defensive: argparse's --format choices currently equal
3450
+ # CACHEABLE_FORMATS, so this is unreachable today; it keeps a
3451
+ # widened choices list from silently caching an unverified format.
3452
+ log(f"[Warning] --cache-dir ignored: {args.format} output is not cacheable")
3453
+ else:
3454
+ try:
3455
+ cache_dir.mkdir(parents=True, exist_ok=True)
3456
+ except OSError as e:
3457
+ print(f"[Error] cannot create --cache-dir {cache_dir}: {e}", file=sys.stderr)
3458
+ return 1
3459
+ if args.format == "avif" and not pil_features.check("avif"):
3460
+ # is_valid_reusable_output() validates an AVIF entry by opening
3461
+ # it with Pillow; without AVIF read support every entry fails
3462
+ # that check, so the cache silently never hits for this format
3463
+ # (fail-closed, but worth telling the operator instead of just
3464
+ # burning space). Newer entries are still stored and evicted.
3465
+ print(
3466
+ "[Warning] --cache-dir will never hit for AVIF: this Pillow build "
3467
+ "cannot read AVIF (needs Pillow >= 11.3 with libavif, e.g. the "
3468
+ "official wheels)",
3469
+ file=sys.stderr,
3470
+ )
3471
+
3472
+ try:
3473
+ output_dir.mkdir(parents=True, exist_ok=True)
3474
+ except OSError as e:
3475
+ # Setup error: nothing has been processed yet, so exit 1 with a
3476
+ # message on stderr and no report (same contract as the argument
3477
+ # checks above).
3478
+ print(f"[Error] cannot create --output directory {output_dir}: {e}", file=sys.stderr)
3479
+ return 1
3480
+ items = [(str(i), str(p.relative_to(source)), args.format) for i, p in enumerate(images)]
3481
+ out_paths = _resolve_collision_free_output_paths(items, output_dir)
3482
+
3483
+ global optimizer
3484
+ optimizer = optimizer_instance or Optimizer(max_concurrency=CONCURRENT_WORKERS)
3485
+ if not optimizer.pngquant_path and not optimizer.oxipng_path and args.format == "png":
3486
+ log(
3487
+ "[Warning] Neither pngquant nor oxipng found in bin/ — PNG results will be much "
3488
+ "weaker than normal (falls back toward Pillow-only handling). Compression will "
3489
+ "still run and nothing will be corrupted, but expect far smaller size savings."
3490
+ )
3491
+
3492
+ if cache_dir_arg and args.format in CACHEABLE_FORMATS:
3493
+ # Hashing the encoder binaries reads a few MB; do it once per run.
3494
+ enc_fp = await asyncio.to_thread(encoder_fingerprint, optimizer, args.format)
3495
+ cache = ContentCache(
3496
+ Path(cache_dir_arg).resolve(), args.format,
3497
+ _settings_fingerprint(
3498
+ args.quality, args.mode, args.max_width, protected_colors,
3499
+ args.dithering, args.keep_exif, args.format,
3500
+ ),
3501
+ enc_fp,
3502
+ )
3503
+
3504
+ total = len(images)
3505
+ counters = {"done": 0, "ok": 0, "failed": 0, "orig": 0, "comp": 0, "cached": 0}
3506
+ # Entry paths stored during this run; handed to evict(protect=...) so a
3507
+ # run never deletes the results it just wrote (see cache.ContentCache.evict).
3508
+ protected_entries: set = set()
3509
+ lock = asyncio.Lock()
3510
+ # No manual semaphore here — Optimizer already bounds concurrent work
3511
+ # internally via its own max_concurrency, so every image is dispatched
3512
+ # via asyncio.gather() and the Optimizer instance does the throttling.
3513
+
3514
+ def fail_record(img_path: Path, error: str, output_name=None, original_size=None) -> dict:
3515
+ """One per-file failure record; every failure path builds it here so
3516
+ the report fields cannot drift between them."""
3517
+ return {
3518
+ "rel": img_path.relative_to(source).as_posix(),
3519
+ "output_name": output_name,
3520
+ "original_size": original_size,
3521
+ "compressed_size": None,
3522
+ "status": "failed",
3523
+ "error": error,
3524
+ }
3525
+
3526
+ async def process(idx: int, img_path: Path):
3527
+ item_id = str(idx)
3528
+ rel = str(img_path.relative_to(source))
3529
+ out_path = out_paths[item_id]
3530
+ if out_path is None:
3531
+ async with lock:
3532
+ counters["done"] += 1
3533
+ counters["failed"] += 1
3534
+ d = counters["done"]
3535
+ records[img_path] = fail_record(
3536
+ img_path, "resolved output path escapes --output directory"
3537
+ )
3538
+ log(f"[{d}/{total}] FAIL {rel}: resolved output path escapes --output directory")
3539
+ return
3540
+ try:
3541
+ out_path.parent.mkdir(parents=True, exist_ok=True)
3542
+ except OSError as e:
3543
+ # Output I/O failure mid-run must look like any other failure: a
3544
+ # per-file record and a clean exit 1, never an unhandled crash
3545
+ # that would abort asyncio.gather() and (with --json) skip the
3546
+ # report entirely.
3547
+ error = f"cannot create output directory {out_path.parent}: {e}"
3548
+ async with lock:
3549
+ counters["done"] += 1
3550
+ counters["failed"] += 1
3551
+ d = counters["done"]
3552
+ records[img_path] = fail_record(img_path, error)
3553
+ log(f"[{d}/{total}] FAIL {rel}: {error}")
3554
+ return
3555
+ cache_key = None
3556
+ cached_hit = False
3557
+ result = None
3558
+ if cache is not None:
3559
+ try:
3560
+ probe = await asyncio.to_thread(cache.probe, img_path, out_path)
3561
+ except OSError:
3562
+ # Unreadable input or cache I/O trouble: fall through to the
3563
+ # normal pipeline, which reports a real input error itself.
3564
+ probe = None
3565
+ if probe is not None:
3566
+ cache_key = probe.key
3567
+ if probe.hit_size is not None:
3568
+ cached_hit = True
3569
+ result = {
3570
+ "success": True, "original_size": probe.original_size,
3571
+ "compressed_size": probe.hit_size, "error": None,
3572
+ }
3573
+ if result is None:
3574
+ result = await optimizer.optimize_png(
3575
+ img_path, out_path,
3576
+ quality=args.quality, max_width=args.max_width, compression_mode=args.mode,
3577
+ protected_colors=protected_colors, dithering=args.dithering,
3578
+ output_format=args.format, keep_exif=args.keep_exif,
3579
+ )
3580
+ if cache is not None and cache_key is not None and result["success"]:
3581
+ try:
3582
+ protected_entries.add(
3583
+ await asyncio.to_thread(cache.store, cache_key, out_path)
3584
+ )
3585
+ except OSError as e:
3586
+ print(f"[Warning] cache write failed for {rel}: {e}", file=sys.stderr)
3587
+ async with lock:
3588
+ counters["done"] += 1
3589
+ d = counters["done"]
3590
+ if result["success"]:
3591
+ counters["ok"] += 1
3592
+ if cached_hit:
3593
+ counters["cached"] += 1
3594
+ counters["orig"] += result["original_size"]
3595
+ counters["comp"] += result["compressed_size"]
3596
+ pct = (
3597
+ round((1 - result["compressed_size"] / result["original_size"]) * 100, 1)
3598
+ if result["original_size"] > 0 else 0
3599
+ )
3600
+ records[img_path] = {
3601
+ "rel": img_path.relative_to(source).as_posix(), "output_name": out_path.name,
3602
+ "original_size": result["original_size"],
3603
+ "compressed_size": result["compressed_size"],
3604
+ "status": (
3605
+ "kept_original" if result.get("kept_original")
3606
+ else "cached" if cached_hit else "compressed"
3607
+ ),
3608
+ "error": None,
3609
+ }
3610
+ log(
3611
+ f"[{d}/{total}] {'HIT ' if cached_hit else 'OK '} {rel} -> {out_path.name} "
3612
+ f"{_fmt_size(result['original_size'])} -> {_fmt_size(result['compressed_size'])} "
3613
+ f"({pct}% saved)"
3614
+ )
3615
+ else:
3616
+ counters["failed"] += 1
3617
+ records[img_path] = fail_record(
3618
+ img_path,
3619
+ result.get("error") or "unknown error",
3620
+ output_name=out_path.name,
3621
+ original_size=result.get("original_size"),
3622
+ )
3623
+ log(f"[{d}/{total}] FAIL {rel}: {result.get('error') or 'unknown error'}")
3624
+
3625
+ await asyncio.gather(*(process(i, p) for i, p in enumerate(images)))
3626
+
3627
+ if cache is not None:
3628
+ try:
3629
+ # Crash leftovers are swept on every run, regardless of the size
3630
+ # cap: with --cache-max-size-mb 0 evict() would never run, and
3631
+ # stale .tmp-* files would accumulate forever.
3632
+ await asyncio.to_thread(cache.sweep_stale_tmp)
3633
+ except OSError as e:
3634
+ print(f"[Warning] cache tmp sweep failed: {e}", file=sys.stderr)
3635
+
3636
+ if cache is not None and cache_max_mb > 0:
3637
+ cache_cap_bytes = cache_max_mb * 1024 * 1024
3638
+ try:
3639
+ evict_stats: dict = {}
3640
+ evicted = await asyncio.to_thread(
3641
+ cache.evict,
3642
+ cache_cap_bytes,
3643
+ protected_entries,
3644
+ evict_stats,
3645
+ )
3646
+ except OSError as e:
3647
+ evicted = 0
3648
+ print(f"[Warning] cache eviction failed: {e}", file=sys.stderr)
3649
+ else:
3650
+ if evict_stats.get("total_after", 0) > cache_cap_bytes:
3651
+ # Only reachable when the cache cannot get under the cap by
3652
+ # evicting unprotected entries: a single entry larger than
3653
+ # the cap, or everything left is this run's fresh writes.
3654
+ print(
3655
+ "[Warning] cache is still over --cache-max-size-mb after eviction "
3656
+ "(entries written this run are protected until the next run, and "
3657
+ "a single entry larger than the cap can never stay under it)",
3658
+ file=sys.stderr,
3659
+ )
3660
+ else:
3661
+ evicted = 0
3662
+
3663
+ log()
3664
+ log(f"Done: {counters['ok']} succeeded, {counters['failed']} failed, {total} total")
3665
+ if n_excluded:
3666
+ log(f"Excluded: {n_excluded} file(s) by --include/--exclude")
3667
+ if cache is not None:
3668
+ log(
3669
+ f"Cache: {counters['cached']} hit, {counters['ok'] - counters['cached']} compressed"
3670
+ + (f", {evicted} evicted" if evicted else "")
3671
+ )
3672
+ if counters["orig"] > 0:
3673
+ saved_pct = round((1 - counters["comp"] / counters["orig"]) * 100, 1)
3674
+ log(f"Total: {_fmt_size(counters['orig'])} -> {_fmt_size(counters['comp'])} ({saved_pct}% saved)")
3675
+ emit_report([records[p] for p in scanned])
3676
+ return 1 if counters["failed"] > 0 else 0
3677
+
3678
+
3679
+ def _download_enabled() -> bool:
3680
+ """Default for --download, with an env opt-out for offline deployments.
3681
+
3682
+ A container image or an air-gapped machine must be able to start without
3683
+ any outbound request, and setting one variable is friendlier than every
3684
+ wrapper script having to remember --no-download.
3685
+ """
3686
+ raw = os.environ.get("IMAGE_OPTIMIZER_NO_DOWNLOAD", "").strip().lower()
3687
+ return raw not in {"1", "true", "yes", "on"}
3688
+
3689
+
3690
+ def _strip_serve_subcommand(argv: list[str]) -> list[str]:
3691
+ """Accept `image-optimizer serve ...` as an alias for `image-optimizer ...`.
3692
+
3693
+ A `serve` subcommand is what users of comparable web apps (open-webui,
3694
+ jupyter) expect, and supporting it costs nothing here: the flags are flat,
3695
+ so dropping the literal word is enough and every historical invocation
3696
+ (`image-optimizer --source ...`) parses exactly as before. Only argv[1] is
3697
+ considered, so a --dir path that happens to be named `serve` is never
3698
+ eaten.
3699
+ """
3700
+ if len(argv) > 1 and argv[1] == "serve":
3701
+ return [argv[0], *argv[2:]]
3702
+ return argv
3703
+
3704
+
3705
+ def main():
3706
+ import argparse
3707
+
3708
+ sys.argv[:] = _strip_serve_subcommand(sys.argv)
3709
+
3710
+ global CONCURRENT_WORKERS, THUMBNAIL_WORKERS, WORKSPACE_CLEANUP_DELAY, SESSION_IDLE_TIMEOUT
3711
+ config = _load_app_config()
3712
+
3713
+ parser = argparse.ArgumentParser(
3714
+ prog="image-optimizer",
3715
+ description="Image Optimizer Web UI",
3716
+ epilog="`image-optimizer serve` is accepted as a synonym for the bare command.",
3717
+ )
3718
+ parser.add_argument(
3719
+ "--host", default=config["host"],
3720
+ help=f"Listen address (default {config['host']!r} / localhost-only, or set 'host' in "
3721
+ f"{_config_file()}). WARNING: this app has no authentication — binding to 0.0.0.0 "
3722
+ f"or a LAN address exposes local file read (scan any directory) and write "
3723
+ f"(output_dir) to anyone on the network.",
3724
+ )
3725
+ def _port_int(raw: str) -> int:
3726
+ # argparse `type` callback: rejects non-integer or out-of-range
3727
+ # BEFORE main() even runs, so `--port notanumber` / `--port 0` /
3728
+ # `--port 99999` exit with the standard argparse usage error rather
3729
+ # than getting handed to the socket layer (where `--port 0` would
3730
+ # bind to an arbitrary OS-assigned port without any user-facing
3731
+ # signal, and out-of-range ints would just be silently truncated).
3732
+ try:
3733
+ v = int(raw)
3734
+ except ValueError:
3735
+ raise argparse.ArgumentTypeError(f"expected an integer, got {raw!r}")
3736
+ if not (1 <= v <= 65535):
3737
+ raise argparse.ArgumentTypeError(f"port must be in 1..65535, got {v}")
3738
+ return v
3739
+
3740
+ parser.add_argument(
3741
+ "--port", type=_port_int, default=config["port"],
3742
+ help=f"Listen port (default {config['port']}, or set 'port' in {_config_file()})",
3743
+ )
3744
+ parser.add_argument(
3745
+ "--workers", type=int, default=config["concurrent_workers"],
3746
+ help=f"How many images to compress concurrently (default {config['concurrent_workers']}, "
3747
+ f"or set 'concurrent_workers' in {_config_file()}). Lower this if pngquant/oxipng "
3748
+ f"are already maxing out your CPU; raise it on a many-core machine.",
3749
+ )
3750
+ parser.add_argument(
3751
+ "--thumbnail-workers", type=int, default=config["thumbnail_workers"],
3752
+ help=f"How many images to thumbnail concurrently during a scan (default "
3753
+ f"{config['thumbnail_workers']}, or set 'thumbnail_workers' in {_config_file()}). "
3754
+ f"Independent from --workers so a scan's I/O-bound thumbnailing can be tuned "
3755
+ f"separately from CPU-bound compression.",
3756
+ )
3757
+ parser.add_argument("--dir", help="Directory to auto-scan on startup (opens the web UI with results pre-loaded)")
3758
+ # Defaults to True to match the historical CLI behavior — the UI checkbox
3759
+ # defaults to False, but `--dir` has always scanned recursively since the
3760
+ # feature shipped. --no-recursive lets an operator override that (e.g. a
3761
+ # folder with thousands of files nested under deep subfolder trees where
3762
+ # only the top-level files are wanted) without breaking existing
3763
+ # invocations that never passed this flag at all. Also used by --source
3764
+ # (CLI mode) below — same meaning, one flag either way.
3765
+ parser.add_argument(
3766
+ "--recursive", action=argparse.BooleanOptionalAction, default=True,
3767
+ help="When used with --dir or --source, scan subfolders too (default True, the "
3768
+ "historical behavior; pass --no-recursive to scan only the top level).",
3769
+ )
3770
+
3771
+ # --- CLI mode: presence of --source means "run headlessly and exit",
3772
+ # skipping the web server entirely. Everything below is only read when
3773
+ # --source is given; see _run_cli.
3774
+ cli_group = parser.add_argument_group("CLI mode (no web server; runs a batch and exits)")
3775
+ cli_group.add_argument(
3776
+ "--source", help="Run headlessly instead of starting the web server: compress every "
3777
+ "supported image under this directory and exit. Requires --output.",
3778
+ )
3779
+ cli_group.add_argument("--output", help="Output directory for --source (required with --source).")
3780
+ cli_group.add_argument(
3781
+ "--quality", choices=["high", "medium", "low"], default="medium",
3782
+ help="Standard/Screenshot mode color-quality floor (default medium).",
3783
+ )
3784
+ cli_group.add_argument(
3785
+ "--format", choices=["png", "jpg", "webp", "avif"], default="png",
3786
+ help="Output format (default png).",
3787
+ )
3788
+ cli_group.add_argument(
3789
+ "--mode", choices=["standard", "lossless", "resize_only", "screenshot"], default="standard",
3790
+ help="Compression mode (default standard). screenshot is PNG-only.",
3791
+ )
3792
+ cli_group.add_argument(
3793
+ "--max-width", type=int, default=0,
3794
+ help="Resize so the longest side is at most this many pixels (default 0 = no resize). "
3795
+ "Required (> 0) when --mode resize_only.",
3796
+ )
3797
+ cli_group.add_argument(
3798
+ "--dithering", action=argparse.BooleanOptionalAction, default=True,
3799
+ help="Dithering for Standard-mode PNG quantization (default enabled; --no-dithering to "
3800
+ "disable, e.g. for UI screenshots with flat colors and text).",
3801
+ )
3802
+ cli_group.add_argument(
3803
+ "--protect-colors", default="",
3804
+ help="Comma-separated hex colors (e.g. '#2ecc71,#ff0000') to prioritize keeping exact "
3805
+ "in Standard mode's palette.",
3806
+ )
3807
+ cli_group.add_argument(
3808
+ "--keep-exif", action="store_true",
3809
+ help="Keep a curated subset of EXIF (camera make/model, date, exposure). GPS and "
3810
+ "Orientation are always stripped regardless. Default: strip all EXIF.",
3811
+ )
3812
+ cli_group.add_argument(
3813
+ "--exclude", action="append", default=[], metavar="GLOB",
3814
+ help="Skip files matching this glob; repeatable. A pattern without '/' matches the "
3815
+ "file name at any depth ('*.bak'); a pattern with '/' matches the path relative "
3816
+ "to --source ('drafts/*'). Case-insensitive on every platform. Wins over --include.",
3817
+ )
3818
+ cli_group.add_argument(
3819
+ "--include", action="append", default=[], metavar="GLOB",
3820
+ help="Only process files matching at least one of these globs; repeatable. Same "
3821
+ "matching rules as --exclude, which is applied afterwards and takes priority.",
3822
+ )
3823
+ cli_group.add_argument(
3824
+ "--json", action="store_true",
3825
+ help="Print the final report as a single JSON object on stdout (per-file status "
3826
+ "compressed/cached/kept_original/excluded/failed, plus a summary). All "
3827
+ "human-readable output moves to stderr so stdout can be piped to a parser.",
3828
+ )
3829
+ cli_group.add_argument(
3830
+ "--cache-dir", metavar="PATH",
3831
+ help="Enable a content-hash result cache stored in PATH. Unchanged inputs with the "
3832
+ "same settings are copied from the cache instead of recompressed, even when "
3833
+ "--output is a fresh directory every run. Must not be inside (or equal to) "
3834
+ "--source or --output. Default: no cache.",
3835
+ )
3836
+ cli_group.add_argument(
3837
+ "--cache-max-size-mb", type=int, default=DEFAULT_CACHE_MAX_MB, metavar="N",
3838
+ help="Cache size cap in MB, enforced after each run by evicting least-recently-used "
3839
+ f"entries (default {DEFAULT_CACHE_MAX_MB}; 0 = unlimited). Only used with --cache-dir.",
3840
+ )
3841
+
3842
+ # The wheel ships no third-party executables (pngquant is GPL-3.0-or-later;
3843
+ # see binaries.py). They are fetched once, verified, and cached per user.
3844
+ bin_group = parser.add_argument_group("Encoder binaries (downloaded on first run)")
3845
+ bin_group.add_argument(
3846
+ "--download", action=argparse.BooleanOptionalAction, default=_download_enabled(),
3847
+ help="Fetch the pinned pngquant/oxipng/cjpeg/avifenc releases on startup when they are "
3848
+ "missing (default enabled). Every download is verified against a pinned SHA-256 "
3849
+ f"and installed into {binaries.binary_dir()}. Use --no-download (or "
3850
+ "IMAGE_OPTIMIZER_NO_DOWNLOAD=1) on an offline/air-gapped machine.",
3851
+ )
3852
+ bin_group.add_argument(
3853
+ "--force-download", action="store_true",
3854
+ help="Re-fetch the pinned binaries even when a matching copy is already installed.",
3855
+ )
3856
+ args = parser.parse_args()
3857
+
3858
+ # Done before the CLI branch so headless `--source` runs get the encoders
3859
+ # too. A failure here only degrades output formats; it must never stop the
3860
+ # app from starting (WebP still works with no external binary at all).
3861
+ # In --json CLI mode every human-readable line must stay off stdout: the
3862
+ # binary bootstrap talks before _run_cli even runs, and its messages would
3863
+ # otherwise break the "exactly one JSON object on stdout" contract
3864
+ # (ensure_binaries defaults to stdout). Web mode and plain CLI runs keep
3865
+ # the historical stdout placement.
3866
+ cli_json = bool(args.source and getattr(args, "json", False))
3867
+ binaries.ensure_binaries(
3868
+ download=args.download,
3869
+ force=args.force_download,
3870
+ out=sys.stderr if cli_json else None,
3871
+ )
3872
+
3873
+ if args.source:
3874
+ CONCURRENT_WORKERS = max(1, args.workers)
3875
+ sys.exit(asyncio.run(_run_cli(args)))
3876
+
3877
+ CONCURRENT_WORKERS = max(1, args.workers)
3878
+ THUMBNAIL_WORKERS = max(1, args.thumbnail_workers)
3879
+ WORKSPACE_CLEANUP_DELAY = config["workspace_cleanup_delay"]
3880
+ SESSION_IDLE_TIMEOUT = config["session_idle_timeout_hours"] * 3600
3881
+
3882
+ if args.dir:
3883
+ d = Path(args.dir).resolve()
3884
+ if d.exists() and d.is_dir():
3885
+ global _cli_prescan_state
3886
+ prescan = AppState()
3887
+ prescan.input_dir = str(d)
3888
+ ws = prescan.new_workspace()
3889
+ images = _scan_images(d, recursive=args.recursive)
3890
+ for idx, img_path in enumerate(images):
3891
+ rel = str(img_path.relative_to(d))
3892
+ thumb_rel = f"thumb/{idx}_{img_path.stem}.jpg"
3893
+ thumb_path = ws / thumb_rel
3894
+ if not thumb_path.exists():
3895
+ _gen_thumbnail(img_path, thumb_path)
3896
+ st = img_path.stat()
3897
+ prescan.files.append({
3898
+ "id": str(idx),
3899
+ "name": rel,
3900
+ "path": str(img_path),
3901
+ "size": st.st_size,
3902
+ "mtime": st.st_mtime,
3903
+ "ctime": st.st_ctime,
3904
+ "thumbnail": f"/api/thumb/{prescan.workspace.name}/{thumb_rel}",
3905
+ })
3906
+ prescan.total = len(prescan.files)
3907
+ _cli_prescan_state = prescan
3908
+ print(f"[Startup] Scanned {len(prescan.files)} images: {d}")
3909
+ else:
3910
+ print(f"[Warning] Directory does not exist: {args.dir}")
3911
+
3912
+ port = _find_free_port(args.host, args.port)
3913
+ if port != args.port:
3914
+ print(f"[Startup] Port {args.port} in use, using port {port} instead")
3915
+
3916
+ if args.host not in ("127.0.0.1", "localhost", "::1"):
3917
+ print(
3918
+ f"[Warning] Binding to {args.host} — this server has NO authentication. "
3919
+ f"Anyone who can reach this address can read any directory on this machine "
3920
+ f"(/api/scan) and write to any writable path (output_dir). Only do this on a "
3921
+ f"network you fully trust."
3922
+ )
3923
+
3924
+ import uvicorn
3925
+ uvicorn.run(app, host=args.host, port=port, reload=False)
3926
+
3927
+
3928
+ if __name__ == "__main__":
3929
+ main()