Relay Extension + Python Receiver — Documentație Completă

1. Arhitectura generală

2. Extensie Chrome MV3

2.1 Structura fișierelor

2.2 Flow capture (passive)

1. Pagina Amazon JS face fetch('/api/loadboard/search', {...})
2. injected.js window.fetch override prinde apelul:
   • Pre-cache: clone request → salvează body + headers (incluzând x-csrf-token)
   • Apoi await origFetch.apply(this, args) → cererea reală merge la Amazon
   • Măsoară fetch_ms = performance.now() - t0 (local, fără telemetrie)
   • Clone response → send()
3. send() trimite window.postMessage({__relay_capture: true, body, ts, fetch_ms, ...}, "*")
4. content_script.js ascultă window.message → forward la background via chrome.runtime.sendMessage
5. background.js trimite payload prin WebSocket la receiver (sau cozează dacă WS offline)

2.3 Flow polling (active)

1. background.js timer (rate configurabil din popup) trimite trigger_active_fetch la fiecare tab eligibil
2. content_script.js forward via postMessage({__relay_active: true, pull_via_ui_click, ...})
3. injected.js handler:
   • DEFAULT pull_via_ui_click=true (Rocket Relay style): găsește butonul Refresh prin #utility-bar .refresh-and-chat-box button + SVG path filter M20.128 2, apoi btn.click() SIMPLU (NU MouseEvent dispatchEvent) — React Amazon răspunde corect. NU există fallback la fetch direct.
   • pull_via_ui_click=false: doFetch direct la URL-ul cached
4. Răspunsul revine via flow passive (mock/Amazon face fetch ca răspuns la click → capture obișnuit)

2.4 Flow book (DOM click style)

Toate cele 10 gates trebuie să treacă, altfel book-ul e blocat:

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 există în DOM (verificat la click time)
6. URL fetch verify (URL conține EXACT tour_id-ul din lock)
7. dom_click_mode = true
8. fetch_url_verify = true
9. LEVEL 4 fetch global block: orice /api/loadboard/{tid}/{v}/option/{oid}/majorVersion/{mv} URL care nu trece gate-urile → fake response cu errorCode: work_opportunity_not_available (cod nativ Amazon, fără string custom suspect)
10. LEVEL 4 XHR global block: idem pentru XMLHttpRequest

2.5 Configurare popup

3. Python Receiver

3.1 Structura fișierelor

3.2 Endpoints HTTP

3.3 Endpoints WebSocket

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

Mesaje ext → receiver

• loadboard_response — capture complet (url, status, body, ts, fetch_ms, source)
• ext_status — status raportat de extensie (poll rate, active flag, errors)
• book_result — rezultat book pentru audit

Mesaje receiver → dispatcher

• add / update — tour nou sau version bump
• gone — tour expirat (TTL grace period)
• ext_status — broadcast la dispatcheri (UI)

Mesaje dispatcher → receiver

• identify — declarare rol
• latency_report — UI raportează latency Date.now() - msg.__server_ts
• ext_command — control remote (pause/resume polling, change rate)

3.4 Variabile de mediu (config.py)

3.5 Safety: book_unlock.json

{
  "enabled": false,
  "token": "",
  "note": "Schimba enabled: true + reload pentru a permite book-uri"
}

Dacă fișierul lipsește SAU enabled !== true → toate book paths blocate (gate redundant cu cel din extension). Token-ul opțional e dovadă suplimentară.

4. Ce poate detecta Amazon — analiză honestă

4.1 Ce VEDE Amazon (telemetria lor)

4.2 Ce NU VEDE Amazon

4.3 Comparație cu Rocket Relay (audit reverse-engineering)

Audit-ul din /var/www/booker-admin/audit/kcnegnbacaohnhpmeckfakhlnahliklf/8.91_0/ confirmă:

• RR folosește același pattern: document.querySelector('.css-q7ppch')?.click() pentru refresh
• RR nu emite niciun event suplimentar către Amazon
• RR rulează din 2021 pe mii de useri fără ban-uri publice

Concluzie: profilul de risc al extensiei noastre = identic cu Rocket Relay. Singurul "tell" semnificativ ar fi RATE de polling agresiv (peste 2-3 req/sec sustained per account).

4.4 Bot signatures pe care le evităm

• ❌ Click cu coordonate (0, 0) → folosim realisticClick() cu coords reale din getBoundingClientRect ± random jitter (pt book buttons)
• ❌ Polling robotic constant → poll_jitter configurabil pentru a randomiza intervalul
• ❌ Polluare pe tab inactiv → poll_only_when_active
• ❌ Cereri cu headers stripped → preservăm TOATE headers din cached request (cookie, csrf, accept-language, etc)

5. Configurare end-to-end

5.1 Setup extensie

1. Load unpacked din chrome://extensions → "Load unpacked" → selectează folder chrome-extension
2. book_unlock.json lângă manifest:

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

   Restartează extensia (chrome://extensions → 🔄) după modificare.
3. Popup: setează Receiver URL = ws://192.168.0.31:9001/ws/stream
4. Bifează Mod activ + Pull via UI click (default ON)
5. Save

5.2 Setup receiver

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

Pe Windows:

• Cross-platform RSS lookup via ctypes nu necesită psutil
• Folosește pythonw.exe receiver.py pentru a rula în background fără console

5.3 Setup booker-admin UI

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

Apoi pe /relay_ws_sources → click pe stats icon → modal cu:

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

6. Pro / Contra de design

✅ Pro

⚠️ Contra / Compromisuri

🔍 Comparativ cu alternative

7. Operațional

7.1 Deploy

Extension (Chrome dev mode)

1. Modifică fișiere local
2. chrome://extensions → 🔄 Reload la "Relay Tour Catcher"
3. F5 pe tab-urile deschise (content scripts nu re-injectează la reload extensie!)

Receiver (Windows 192.168.0.31)

# Stop curent
# (taskkill /F /IM python.exe sau Ctrl+C în consolă)
# Copy fișiere noi
scp receiver.py user@192.168.0.31:/path/to/app/
# Restart
python receiver.py

Booker-admin UI

• Edit templates/relay_ws_sources/*.html și plib/relay/relay_ws_sources_api/*.php local
• Clear Smarty cache: rm /var/www/booker-admin/templates_c/*relay_ws_sources*
• F5 pagină

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 pentru issues istorice
• UI charts în modal stats — vizualizare live 1s refresh

8. Limitări cunoscute

1. Auto-paginate max 20 pagini — dacă userul cere resultSize=50 și sunt 2000 tururi, se opresc la 1000 (20 × 50)
2. POLL_HISTORY in-memory — pierdut la restart receiver
3. RAW_RING in-memory — idem
4. Reports DB SQLite — single-writer; pentru concurrent receivers trebuie PostgreSQL
5. Book click fallback unic — DOM click; fetch direct e disabled by design (riscant)
6. CSRF generat dynamic la mock — token expiră la restart container

9. Glosar

• Tour / WorkOpportunity (WO) — un job de transport Amazon Relay
• Pool — set de tururi active în memoria receiver-ului
• Grace period — TTL după care un tur nevăzut e șters din pool
• Dispatcher — orice client WS care consumă broadcasts (UI, agent, etc)
• Capture — un response /api/loadboard/search interceptat
• Passive — capture-ul vine de la fetch-ul propriu al paginii Amazon
• Active — capture-ul vine de la trigger-ul programat al extensiei
• Round complete — răspuns cu nextItemToken=0 (ultima pagină dintr-o secvență)
• Fast Book — buton injectat de extensie pe fiecare card de tur pentru book one-click
• Simulation mode — dry-run: highlight + sunet, fără click real pe Reservar

10. Backup-uri

Toate modificările majore au backup în /var/www/booker-admin/backups/:

• relay_stats_20260525_020909/ — înainte de adăugarea charts + raw ring + ZIP export

Pentru rollback complet: copy din backup în loc.