generated from coulomb/repo-seed
Switch to HTTP Basic Auth and improve PDF detection
- Replace token-based auth with HTTP Basic Authentication per Binect API v1 spec - Improve PDF detection: check current tab first, then background service, fallback to recent downloads - Add password visibility toggle in login form - Add extensive debug logging throughout for troubleshooting - Update manifest with alarms, activeTab permissions and <all_urls> host permission - Add documentation files and development helper scripts - Add Binect API specs for reference Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
303
DOWNLOAD_DETECTION_FIXES.md
Normal file
303
DOWNLOAD_DETECTION_FIXES.md
Normal file
@@ -0,0 +1,303 @@
|
||||
# Download Detection Debugging & Fixes
|
||||
|
||||
## Summary
|
||||
|
||||
I've added comprehensive debugging and a fallback mechanism to help diagnose and work around download detection issues.
|
||||
|
||||
## Changes Made
|
||||
|
||||
### 1. **Comprehensive Debug Logging**
|
||||
|
||||
**Service Worker (src/background/service-worker.ts):**
|
||||
- All events now log with `[Service Worker]` prefix
|
||||
- Shows when service worker loads/reloads
|
||||
- Logs PDF detection callbacks
|
||||
- Logs message handling from popup
|
||||
|
||||
**PDF Detector (src/utils/pdf-detector.ts):**
|
||||
- All download events logged with `[PDF Detector]` prefix
|
||||
- Shows download state changes (in_progress → complete)
|
||||
- Logs download item details (filename, mime, state, url)
|
||||
- Confirms when PDF is detected vs. ignored
|
||||
|
||||
**Popup (src/popup/popup.ts):**
|
||||
- All PDF loading operations logged with `[Popup]` prefix
|
||||
- Shows detection priority: tab viewer → background → fallback
|
||||
- Logs results of each detection method
|
||||
|
||||
### 2. **Fallback Mechanism**
|
||||
|
||||
**New function: `checkRecentDownloads()` (src/popup/popup.ts:254-298)**
|
||||
- Directly queries Chrome's downloads API for recent PDFs
|
||||
- Checks last 20 downloads
|
||||
- Finds most recent completed PDF
|
||||
- **Works even if service worker missed the download event**
|
||||
|
||||
**PDF Detection Priority:**
|
||||
1. Current tab (PDF viewer) - NEW
|
||||
2. Background service worker (download event listener)
|
||||
3. **Recent downloads fallback** - NEW
|
||||
4. No PDF detected
|
||||
|
||||
This triple-layer approach ensures PDFs are detected even if the service worker is sleeping.
|
||||
|
||||
## How to Debug
|
||||
|
||||
### Step 1: Reload Extension
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
Then reload at `chrome://extensions/`
|
||||
|
||||
### Step 2: Open Consoles
|
||||
|
||||
**Service Worker Console:**
|
||||
1. Go to `chrome://extensions/`
|
||||
2. Click "service worker" link under BinectChrome
|
||||
3. **Keep this open while testing**
|
||||
|
||||
**Popup Console:**
|
||||
1. Click the extension icon
|
||||
2. Right-click inside popup → "Inspect"
|
||||
3. View console
|
||||
|
||||
### Step 3: Download a Test PDF
|
||||
|
||||
**Test URL:**
|
||||
```
|
||||
https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
|
||||
```
|
||||
|
||||
**Method 1: Direct download**
|
||||
- Right-click link → "Save link as..."
|
||||
- Save to Downloads
|
||||
|
||||
**Method 2: View in browser**
|
||||
- Paste URL in address bar
|
||||
- Let Chrome open it in viewer
|
||||
- Click extension icon
|
||||
|
||||
### Step 4: Check Logs
|
||||
|
||||
**Expected Service Worker logs:**
|
||||
```
|
||||
[Service Worker] ===== BinectChrome service worker loaded =====
|
||||
[Service Worker] Initializing PDF detection...
|
||||
[PDF Detector] Starting PDF detection, registering download listener
|
||||
[PDF Detector] Listener registered successfully
|
||||
|
||||
# When download completes:
|
||||
[PDF Detector] Download changed: {id: X, state: {...}, stateValue: "complete"}
|
||||
[PDF Detector] Download complete, searching for item: X
|
||||
[PDF Detector] Search results: 1 items
|
||||
[PDF Detector] Download item: {id: X, filename: "dummy.pdf", mime: "application/pdf", ...}
|
||||
[PDF Detector] PDF detected!
|
||||
[Service Worker] PDF DETECTED CALLBACK: dummy.pdf
|
||||
[Service Worker] Badge updated, PDF stored in memory
|
||||
```
|
||||
|
||||
**Expected Popup logs:**
|
||||
```
|
||||
[Popup] Loading last PDF...
|
||||
[Popup] No PDF in current tab, checking background script...
|
||||
[Service Worker] Message received: getLastPDF
|
||||
[Service Worker] Returning last PDF: dummy.pdf
|
||||
[Popup] Background returned PDF: dummy.pdf
|
||||
```
|
||||
|
||||
**If service worker missed it (fallback):**
|
||||
```
|
||||
[Popup] Loading last PDF...
|
||||
[Popup] No PDF in current tab, checking background script...
|
||||
[Service Worker] Message received: getLastPDF
|
||||
[Service Worker] Returning last PDF: none
|
||||
[Popup] Background has no PDF, checking recent downloads as fallback...
|
||||
[Popup] Checked recent downloads: 15 items
|
||||
[Popup] Found recent PDF: dummy.pdf
|
||||
```
|
||||
|
||||
## Common Issues & Solutions
|
||||
|
||||
### Issue 1: No Service Worker Logs
|
||||
|
||||
**Symptom:** Service worker console is empty or shows "Inactive"
|
||||
|
||||
**Solution:**
|
||||
- Click the extension icon (wakes it up)
|
||||
- Or go to `chrome://serviceworker-internals/` and click "Start"
|
||||
- Check for registration errors
|
||||
|
||||
### Issue 2: Service Worker Not Waking for Downloads
|
||||
|
||||
**Symptom:** Download completes but no `[PDF Detector]` logs appear
|
||||
|
||||
**This is the main issue with Manifest V3 service workers!**
|
||||
|
||||
**Diagnosis:**
|
||||
1. Open service worker console
|
||||
2. Download a PDF
|
||||
3. Watch if service worker console gets new logs
|
||||
|
||||
**If no logs:** Service worker didn't wake up for the download event
|
||||
|
||||
**Workaround:** The fallback mechanism handles this! When you open the popup, it checks recent downloads directly.
|
||||
|
||||
### Issue 3: Badge Not Updating
|
||||
|
||||
**Symptom:** PDF downloads but badge stays empty
|
||||
|
||||
**Cause:** Service worker detected PDF but couldn't update badge (possibly terminated)
|
||||
|
||||
**Solution:** The fallback still works - open popup to see the PDF
|
||||
|
||||
### Issue 4: PDF Shows in Popup But Disappears
|
||||
|
||||
**Symptom:** PDF shows up, but after a few minutes it's gone
|
||||
|
||||
**Cause:** Service worker memory is ephemeral - when it terminates, `lastDetectedPDF` is lost
|
||||
|
||||
**Solution:** The fallback mechanism re-fetches from recent downloads each time popup opens
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
- [ ] Build extension: `npm run build`
|
||||
- [ ] Reload extension at `chrome://extensions/`
|
||||
- [ ] Open service worker console
|
||||
- [ ] Download test PDF (right-click → Save link as)
|
||||
- [ ] Check service worker logs for detection
|
||||
- [ ] Check if badge shows "1"
|
||||
- [ ] Open popup - should show PDF
|
||||
- [ ] Wait 2 minutes (service worker sleeps)
|
||||
- [ ] Download another PDF
|
||||
- [ ] Open popup - should show PDF (even if service worker missed it)
|
||||
- [ ] Open PDF in browser tab (view, don't download)
|
||||
- [ ] Open popup - should detect tab viewer
|
||||
|
||||
## Known Limitations
|
||||
|
||||
### 1. Service Worker Lifecycle (Manifest V3)
|
||||
Service workers shut down after 30 seconds of inactivity. This is by design in Manifest V3.
|
||||
|
||||
**Impact:**
|
||||
- Download event listener may not fire if service worker is sleeping
|
||||
- Badge may not update immediately after download
|
||||
- `lastDetectedPDF` is lost when service worker terminates
|
||||
|
||||
**Mitigation:**
|
||||
- Fallback mechanism checks recent downloads
|
||||
- Works reliably despite service worker sleep
|
||||
- Badge updates when popup opens
|
||||
|
||||
### 2. File URLs
|
||||
Chrome extensions can't access `file://` URLs by default.
|
||||
|
||||
**Impact:** If PDF is downloaded and opened from disk, can't re-fetch for upload
|
||||
|
||||
**Solution:** Use the original download URL (which we store)
|
||||
|
||||
### 3. Authenticated Downloads
|
||||
Some PDFs require authentication cookies.
|
||||
|
||||
**Impact:** Re-fetching PDF may fail if session expired
|
||||
|
||||
**Solution:** `fetchPDFBytes()` uses `credentials: 'include'` to send cookies
|
||||
|
||||
## Advanced Debugging
|
||||
|
||||
### Manual Download Check
|
||||
Run in Service Worker console:
|
||||
```javascript
|
||||
chrome.downloads.search({ limit: 10, orderBy: ['-startTime'] }, (items) => {
|
||||
console.log('Recent downloads:');
|
||||
items.forEach(item => {
|
||||
const isPDF = item.filename.toLowerCase().endsWith('.pdf') ||
|
||||
item.mime === 'application/pdf';
|
||||
console.log(` ${item.filename} - PDF: ${isPDF} - State: ${item.state}`);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Test Download Listener
|
||||
Run in Service Worker console:
|
||||
```javascript
|
||||
chrome.downloads.download({
|
||||
url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf',
|
||||
filename: 'test-download.pdf'
|
||||
}, (downloadId) => {
|
||||
console.log('Started download:', downloadId);
|
||||
});
|
||||
```
|
||||
|
||||
Watch for `[PDF Detector]` logs.
|
||||
|
||||
### Check Permissions
|
||||
Run in Service Worker console:
|
||||
```javascript
|
||||
chrome.permissions.contains({ permissions: ['downloads'] }, (result) => {
|
||||
console.log('Has downloads permission:', result);
|
||||
});
|
||||
```
|
||||
|
||||
## Recommended Testing Flow
|
||||
|
||||
**For Development:**
|
||||
1. Use PDF viewer detection (open PDF in tab)
|
||||
2. This bypasses download detection entirely
|
||||
3. Most reliable for testing API integration
|
||||
|
||||
**For Download Detection Testing:**
|
||||
1. Open both service worker and popup consoles
|
||||
2. Download a PDF
|
||||
3. Watch logs in real-time
|
||||
4. Verify fallback works even if service worker missed it
|
||||
|
||||
## Next Steps
|
||||
|
||||
**If download detection is still unreliable:**
|
||||
|
||||
### Option A: Accept Viewer Detection as Primary
|
||||
- PDF viewer detection works reliably
|
||||
- Download detection becomes secondary
|
||||
- Users can open PDFs in browser instead of downloading
|
||||
|
||||
### Option B: Persist Detected PDFs
|
||||
- Store detected PDFs in `chrome.storage` instead of memory
|
||||
- Survives service worker restarts
|
||||
- Requires storage cleanup logic
|
||||
|
||||
### Option C: Poll Downloads Periodically
|
||||
- Set up an alarm to check recent downloads every minute
|
||||
- More resource intensive
|
||||
- Very reliable
|
||||
|
||||
## Files Changed
|
||||
|
||||
1. `src/background/service-worker.ts` - Added debug logging
|
||||
2. `src/utils/pdf-detector.ts` - Added debug logging
|
||||
3. `src/popup/popup.ts` - Added debug logging and fallback mechanism
|
||||
4. `DEBUG_DOWNLOAD_DETECTION.md` - Comprehensive debugging guide
|
||||
5. `DOWNLOAD_DETECTION_FIXES.md` - This file
|
||||
|
||||
## Support
|
||||
|
||||
If download detection still doesn't work:
|
||||
1. Follow `DEBUG_DOWNLOAD_DETECTION.md`
|
||||
2. Export console logs from both service worker and popup
|
||||
3. Include Chrome version: `chrome://version/`
|
||||
4. Report to bernd.worsch@binect.de
|
||||
|
||||
## Workaround
|
||||
|
||||
**The PDF viewer detection is fully functional and reliable!**
|
||||
|
||||
Instead of relying on download detection:
|
||||
1. Open PDFs in Chrome (paste URL in address bar)
|
||||
2. Click extension icon
|
||||
3. PDF is detected from current tab
|
||||
4. Send to Binect
|
||||
|
||||
This approach:
|
||||
- ✅ Always works
|
||||
- ✅ No service worker timing issues
|
||||
- ✅ Better user experience (no downloads folder clutter)
|
||||
- ✅ Easier to test API integration
|
||||
Reference in New Issue
Block a user