[PR #137] [MERGED] [cli] Add a --debug flag that writes a shareable diagnostic log #141

New issue

Closed

opened 2026-10-13 19:47:53 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-13 19:47:53 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Glitchy-Sheep/boosty-downloader/pull/137
Author: @Glitchy-Sheep
Created: 8/10/2026
Status: ✅ Merged
Merged: 8/10/2026
Merged by: @Glitchy-Sheep

Base: main ← Head: feat/debug-flag

📝 Commits (4)

9f0ce51 feat: 🔍 --debug flag writes a detailed log file
131996c fix: 🐛 Network errors name the real cause instead of blaming the internet
4f90994 feat: 🔍 The debug log sees every request through a session observer
841e380 test: ✅ Cover --debug reporting and document the flag

📊 Changes

13 files changed (+313 additions, -25 deletions)

View changed files

📝 CHANGELOG.md (+8 -0)
📝 README.md (+2 -0)
📝 boosty_downloader/main.py (+10 -24)
📝 boosty_downloader/src/application/di/app_environment.py (+4 -0)
📝 boosty_downloader/src/cli/cli_options.py (+37 -0)
➕ boosty_downloader/src/cli/error_reporting.py (+43 -0)
📝 boosty_downloader/src/infrastructure/loggers/base.py (+5 -1)
➕ boosty_downloader/src/infrastructure/loggers/debug_file.py (+75 -0)
➕ boosty_downloader/src/infrastructure/loggers/request_tracing.py (+48 -0)
➕ test/unit/cli/__init__.py (+0 -0)
➕ test/unit/cli/error_reporting_test.py (+62 -0)
➕ test/unit/loggers/__init__.py (+0 -0)
➕ test/unit/loggers/request_tracing_test.py (+19 -0)

📄 Description

[cli] Add a --debug flag that writes a shareable diagnostic log

Summary

Issue #109: a user hit a DNS failure and the app answered with a generic connection message - nothing to diagnose, nothing to attach to the report. Now network errors say what actually broke, and --debug writes a log file made for attaching to GitHub issues.

How it works

--debug on the root command starts boosty-downloader-debug.log in the current directory: app version, platform, Python, argv
A TraceConfig observer on the shared HTTP session logs every request - API calls, file downloads, retries - the callers never know the log exists
URLs are logged without their query string: signed CDN links carry expiring keys, and the log is meant for public issues
Network errors branch by cause: a DNS failure names the host and suggests another DNS (1.1.1.1) or a VPN that covers all apps
Every network error ends with a pointer at the debug log; full tracebacks go to the file, the screen stays at INFO and up

Before / After

Before: any network failure printed the same generic message; the user from #109 was told to check their internet while their browser worked fine (browsers often use their own DNS).

After: the screen names the failing host and the likely fix; --debug produces a log with every request and full tracebacks, safe to attach publicly.

Tests

redacted_url tests: the signed query is cut off, plain URLs stay intact
Error reporting tests: DNS errors name the host and cause, generic errors keep the real exception type, every network error points at the debug log
Live repro: a request to api.boosty.invalid (guaranteed NXDOMAIN) through the real network stack raised ClientConnectorDNSError, showed the new message and left the request line plus traceback in the log

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/Glitchy-Sheep/boosty-downloader/pull/137 **Author:** [@Glitchy-Sheep](https://github.com/Glitchy-Sheep) **Created:** 8/10/2026 **Status:** ✅ Merged **Merged:** 8/10/2026 **Merged by:** [@Glitchy-Sheep](https://github.com/Glitchy-Sheep) **Base:** `main` ← **Head:** `feat/debug-flag` --- ### 📝 Commits (4) - [`9f0ce51`](https://github.com/Glitchy-Sheep/boosty-downloader/commit/9f0ce511e23ce451f29da8c49b8733ee43e1127f) feat: :mag: --debug flag writes a detailed log file - [`131996c`](https://github.com/Glitchy-Sheep/boosty-downloader/commit/131996c4c5ddcc03473dd300a01d5a8a88400fa0) fix: :bug: Network errors name the real cause instead of blaming the internet - [`4f90994`](https://github.com/Glitchy-Sheep/boosty-downloader/commit/4f90994ac49fd7ca7879a89eea3e0e53ad85af68) feat: :mag: The debug log sees every request through a session observer - [`841e380`](https://github.com/Glitchy-Sheep/boosty-downloader/commit/841e3805d256d02e71b033929abec646e6dafe26) test: :white_check_mark: Cover --debug reporting and document the flag ### 📊 Changes **13 files changed** (+313 additions, -25 deletions) <details> <summary>View changed files</summary> 📝 `CHANGELOG.md` (+8 -0) 📝 `README.md` (+2 -0) 📝 `boosty_downloader/main.py` (+10 -24) 📝 `boosty_downloader/src/application/di/app_environment.py` (+4 -0) 📝 `boosty_downloader/src/cli/cli_options.py` (+37 -0) ➕ `boosty_downloader/src/cli/error_reporting.py` (+43 -0) 📝 `boosty_downloader/src/infrastructure/loggers/base.py` (+5 -1) ➕ `boosty_downloader/src/infrastructure/loggers/debug_file.py` (+75 -0) ➕ `boosty_downloader/src/infrastructure/loggers/request_tracing.py` (+48 -0) ➕ `test/unit/cli/__init__.py` (+0 -0) ➕ `test/unit/cli/error_reporting_test.py` (+62 -0) ➕ `test/unit/loggers/__init__.py` (+0 -0) ➕ `test/unit/loggers/request_tracing_test.py` (+19 -0) </details> ### 📄 Description # [cli] Add a --debug flag that writes a shareable diagnostic log ## Summary Issue #109: a user hit a DNS failure and the app answered with a generic connection message - nothing to diagnose, nothing to attach to the report. Now network errors say what actually broke, and `--debug` writes a log file made for attaching to GitHub issues. ## How it works - `--debug` on the root command starts `boosty-downloader-debug.log` in the current directory: app version, platform, Python, argv - A `TraceConfig` observer on the shared HTTP session logs every request - API calls, file downloads, retries - the callers never know the log exists - URLs are logged without their query string: signed CDN links carry expiring keys, and the log is meant for public issues - Network errors branch by cause: a DNS failure names the host and suggests another DNS (1.1.1.1) or a VPN that covers all apps - Every network error ends with a pointer at the debug log; full tracebacks go to the file, the screen stays at INFO and up ## Before / After **Before:** any network failure printed the same generic message; the user from #109 was told to check their internet while their browser worked fine (browsers often use their own DNS). **After:** the screen names the failing host and the likely fix; `--debug` produces a log with every request and full tracebacks, safe to attach publicly. ## Tests - `redacted_url` tests: the signed query is cut off, plain URLs stay intact - Error reporting tests: DNS errors name the host and cause, generic errors keep the real exception type, every network error points at the debug log - Live repro: a request to `api.boosty.invalid` (guaranteed NXDOMAIN) through the real network stack raised `ClientConnectorDNSError`, showed the new message and left the request line plus traceback in the log --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-13 19:47:53 +00:00