Relay Extension + Python Receiver — Documentație Completă

1. Overall architecture

2. Chrome MV3 Extension

2.1 File structure

2.2 Capture flow (passive)

1. Amazon page JS calls fetch('/api/loadboard/search', {...})
2. injected.js window.fetch override intercepts the call:
   • Pre-cache: clone request → saves body + headers (including x-csrf-token)
   • Then await origFetch.apply(this, args) → real request goes to Amazon
   • Measures fetch_ms = performance.now() - t0 (locally, no telemetry)
   • Clone response → send()
3. send() dispatches window.postMessage({__relay_capture: true, body, ts, fetch_ms, ...}, "*")
4. content_script.js listens to window.message → forwards to background via chrome.runtime.sendMessage
5. background.js sends payload via WebSocket to receiver (or queues if WS offline)

2.3 Polling flow (active)

1. background.js timer (rate configurable from popup) sends trigger_active_fetch to each eligible tab
2. content_script.js forwards via postMessage({__relay_active: true, pull_via_ui_click, ...})
3. injected.js handler:
   • DEFAULT pull_via_ui_click=true: finds the Refresh button via #utility-bar .refresh-and-chat-box button + SVG path filter M20.128 2, then SIMPLE btn.click() (NOT MouseEvent dispatchEvent) — Amazon React responds correctly. NO fallback to direct fetch.
   • pull_via_ui_click=false: direct doFetch to the cached URL
4. Response arrives via passive flow (mock/Amazon makes fetch in response to click → normal capture)

2.4 Book flow (DOM click style)

All 10 gates must pass, otherwise book is blocked:

1. book_unlock.json exists + enabled: true
2. Popup toggle "Book ENABLED" = ON
3. BOOK_HARDCODED_CONFIG.enabled = true (în code)
4. Tour ID în lock (__relay_book_in_progress)
5. Card exists in DOM (verified at click time)
6. URL fetch verify (URL contains EXACT tour_id from lock)
7. dom_click_mode = true
8. fetch_url_verify = true
9. LEVEL 4 global fetch block: any /api/loadboard/{tid}/{v}/option/{oid}/majorVersion/{mv} URL not passing gates → fake response with errorCode: work_opportunity_not_available (native Amazon code, no suspicious custom string)
10. LEVEL 4 global XHR block: same for XMLHttpRequest

2.5 Popup configuration

3. Python Receiver

3.1 File structure

3.2 HTTP endpoints

3.3 WebSocket endpoints

Path: WS /ws/stream — Multiplex: ext (push captures) sau dispatcher (recv broadcasts) după primul mesaj identify

Messages ext → receiver

• loadboard_response — full capture (url, status, body, ts, fetch_ms, source)
• ext_status — status reported by extension (poll rate, active flag, errors)
• book_result — book result for audit

Messages receiver → dispatcher

• add / update — new tour or version bump
• gone — expired tour (TTL grace period)
• ext_status — broadcast to dispatchers (UI)

Messages dispatcher → receiver

• identify — role declaration
• latency_report — UI reports latency Date.now() - msg.__server_ts
• ext_command — remote control (pause/resume polling, change rate)

3.4 Environment variables (config.py)

3.5 Safety: book_unlock.json

{
  "enabled": false,
  "token": "",
  "note": "Set enabled: true + reload to allow book attempts"
}

If the file is missing OR enabled !== true → all book paths blocked (gate redundant with extension one). Optional token is extra proof.

4. What Amazon can detect — analiză honestă

4.1 What Amazon SEES (their telemetry)

4.2 What Amazon DOES NOT SEE

4.3 Comparison with empirical real-world testing

The audit at /var/www/booker-admin/audit/kcnegnbacaohnhpmeckfakhlnahliklf/8.91_0/ confirms:

• Same pattern is used: document.querySelector('.css-q7ppch')?.click() for refresh
• No extra event is emitted to Amazon
• Confirmed in production usage without bans

Conclusion: our extension's risk profile = same as a real user clicking the UI. The only significant "tell" would be aggressive polling RATE (over 2-3 req/sec sustained per account).

4.4 Bot signatures we avoid

• ❌ Click with coordinates (0, 0) → we use realisticClick() with real coords from getBoundingClientRect ± random jitter (for book buttons)
• ❌ Constant robotic polling → poll_jitter configurable to randomize the interval
• ❌ Polling on inactive tab → poll_only_when_active
• ❌ Requests with stripped headers → we preserve ALL headers from cached request (cookie, csrf, accept-language, etc)

5. End-to-end configuration

5.1 Extension setup

1. Load unpacked from chrome://extensions → "Load unpacked" → select folder chrome-extension
2. book_unlock.json next to manifest:

   {"enabled": true, "token": "ceva-secret"}

   Restart the extension (chrome://extensions → 🔄) after modification.
3. Popup: set Receiver URL = ws://192.168.0.31:9001/ws/stream
4. Check Mod activ + Pull via UI click (default ON)
5. Save

5.2 Receiver setup

cd python-receiver/app
python3 -m venv venv && source venv/bin/activate
pip install fastapi uvicorn  # + opțional: psutil

# .env (lângă receiver.py)
RECEIVER_PORT=9001
RAW_RING_SIZE=1000
FAIL_AUTO_STOP_THRESHOLD=20
GRACE_PERIOD_S=1.5

# book_unlock.json
{"enabled": true, "token": ""}

# Start
python3 receiver.py

On Windows:

• Cross-platform RSS lookup via ctypes does not require psutil
• Use pythonw.exe receiver.py to run in background without console

5.3 Booker-admin UI setup

INSERT INTO relay_ws_sources (user_id, name, url, active)
VALUES (1, 'LocalReceiver', 'ws://192.168.0.31:9001/ws/stream', 1);

Then on /relay_ws_sources → click stats icon → modal with:

• 6 live charts (status pie, ext→recv latency, body size, polls/min, fetch ms, recv→UI ms)
• "Last captures" tab + "Raw JSONs in RAM" tab
• "Download ZIP" button for last 50/100/500/1000

6. Pros / Cons by design

✅ Pros

⚠️ Cons / Trade-offs

🔍 Compared to alternatives

7. Operations

7.1 Deploy

Extension (Chrome dev mode)

1. Modify files locallyly
2. chrome://extensions → 🔄 Reload "Relay Tour Catcher"
3. F5 on open tabs (content scripts do not re-inject on extension reload!)

Receiver (Windows 192.168.0.31)

# Stop current
# (taskkill /F /IM python.exe or Ctrl+C in console)
# Copy new files
scp receiver.py user@192.168.0.31:/path/to/app/
# Restart
python receiver.py

Booker-admin UI

• Edit templates/relay_ws_sources/*.html and plib/relay/relay_ws_sources_api/*.php locally
• Clear Smarty cache: rm /var/www/booker-admin/templates_c/*relay_ws_sources*
• F5 page

7.2 Debug

7.3 Monitoring

• /admin/stats — pool size, ext_clients, uptime, RAM RSS
• /admin/insights — recent polls, latency avg + time series, consecutive_fails
• Reports DB — /admin/reports/events?level=error for historical issues
• UI charts in stats modal — live 1s refresh visualization

8. Known limitations

1. Auto-paginate max 20 pages — if user requests resultSize=50 and sunt 2000 tururi, se opresc la 1000 (20 × 50)
2. POLL_HISTORY in-memory — lost on receiver restart
3. RAW_RING in-memory — same
4. SQLite Reports DB — single-writer; for concurrent receivers requires PostgreSQL
5. Single book click fallback — DOM click; direct fetch is disabled by design (risky)
6. CSRF generated dynamically at mock — token expires on container restart

9. Glossary

• Tour / WorkOpportunity (WO) — an Amazon Relay transport job
• Pool — set of active tours in receiver memory
• Grace period — TTL after which an unseen tour is removed from the pool
• Dispatcher — any WS client consuming broadcasts (UI, agent, etc)
• Capture — a response /api/loadboard/search intercepted
• Passive — capture comes from the page's own Amazon fetch
• Active — capture comes from the extension's scheduled trigger
• Round complete — response with nextItemToken=0 (last page of a sequence)
• Fast Book — buton injectat de extensie on each card de tur pentru book one-click
• Simulation mode — dry-run: highlight + sound, no real click on Reservar

10. Backups

All major changes have backups in /var/www/booker-admin/backups/:

• relay_stats_20260525_020909/ — before adding charts + raw ring + ZIP export

For full rollback: copy from backup in place.