first commit

README.md

@@ -0,0 +1,202 @@
+# X360 Web Queue — Linux / Docker / Xbox 360 RGH
+
+Samodzielna aplikacja WWW do pobierania i przygotowywania posiadanych legalnie obrazow gier Xbox 360. Wszystkie zadania wykonywane sa na serwerze/VM, niezaleznie od otwartej karty przegladarki.
+
+## Start
+
+Wymagania: **Linux x86_64**, Docker Engine z wtyczka Docker Compose, minimum ok. 2 GB RAM (zalecane 4 GB podczas budowania), duzo miejsca na dane.
+
+```bash
+unzip x360-web-queue-xbox.zip
+cd x360-web-queue
+# /xbox musi istniec i byc zapisywalny na hoscie Linux
+./setup.sh
+```
+
+`setup.sh` przygotuje katalogi w `/xbox`, sam utworzy `.env` z mocnymi haslami i wykona `docker compose up -d --build`. Przy pierwszym starcie budowane sa `xdvdfs`, `iso2god-rs` i pomocniczy klient BitTorrent Go. Wirtualka potrzebuje dostepu do Docker Hub, GitHub, crates.io i proxy.golang.org. Na gospodarzu nie musisz instalowac Rusta ani Go.
+
+Otworz `http://IP_TWOJEJ_WIRTUALKI:8088` i zaloguj sie jako `admin` za pomoca hasla wypisanego przez `setup.sh` (takze w `.env`).
+
+Jesli Docker nie byl jeszcze zainstalowany, zainstaluj go, a pozniej:
+
+```bash
+./setup.sh
+# lub, po utworzeniu .env:
+docker compose up -d --build
+```
+
+Aktualny stan i logi:
+
+```bash
+docker compose ps
+docker compose logs -f --tail=100
+```
+
+## Interfejs
+
+Plaski panel w ciemnych barwach, lokalne ikony SVG (bez CDN), filtrowanie kolejki i widok mobilny. Interfejs nie wymaga dodatkowych zaleznosci JS i zachowuje API dotychczasowej aplikacji.
+
+## Zrodla
+
+- **HTTPS/HTTP**: wklej bezposredni adres pliku ISO/ZIP/7z/RAR, rowniez z serwisow umozliwiajacych normalny bezposredni transfer.
+- **Magnet**: panel automatycznie usuwa z wklejonego adresu HTML `&`, przypadkowe znaki `\` i lamanie linii, sprawdza hash, a nastepnie pobiera wylacznie metadane torrenta. Metadane pobiera klient Go (`anacrolix/torrent`, taki sam stos jak `minerva-pick`), bez pobierania plikow gry. Okno pokazuje czas, liczbe polaczen i znanych peerow. Po 5 minutach bez metadanych pojawia sie blad zamiast bezterminowego oczekiwania. Parametr `so=` ustawia wstepne zaznaczenie (od 0). Transfer danych rusza dopiero po wyborze plikow.
+- **Plik .torrent**: opcja `Wczytaj .torrent` w zakladce Link / magnet oraz w oknie podgladu. Pozwala natychmiast uzyskac liste plikow bez czekania na peerow. Maks. 32 MiB metadanych. Wczytanie .torrent *nie rozpoczyna* pobierania zawartosci, dopiero przycisk `Pobierz wybrane`. Dziala z duzymi katalogami Minerva (widok pokazuje maks. 500 plikow naraz, filtr pozwala wyszukac reszte).
+- **Internet Archive**: zakladka umozliwia zalogowanie e-mailem i haslem Archive.org (mechanizm xauthn stosowany w oficjalnych narzedziach), nastepnie wklej `https://archive.org/details/IDENTYFIKATOR` i wybierz pliki. Aplikacja przechowuje **tylko ciasteczka sesji**, a nie haslo. Pliki sa pobierane bezposrednio przez backend z sesja Archive.org, bez starego przekaznika aria2. **Wszystkie pliki jednego zadania sa pobierane rownolegle, maksymalnie 50 jednoczesnie**. Duze pliki sa dodatkowo dzielone na segmenty HTTP Range. Limit `ARCHIVE_CONNECTIONS=50` dotyczy **sumy polaczen HTTP wszystkich plikow zadania**, nie kazdego pliku osobno. Postep segmentow jest zachowywany po restarcie; pobieranie wznawia tylko brakujace bajty. Gdy serwer nie obsluguje Range albo zwraca niezgodne zakresy, aplikacja automatycznie przechodzi na jedno polaczenie. Dzialaja ponowienia HTTP 500/502/503/504/429 i kontrola wersji pliku za pomoca ETag / Last-Modified, jesli serwer je podaje. Ciasteczka sesji nie trafiaja do aria2 ani do logow. Logowanie nie zapewnia dostepu do plikow niedostepnych dla Twojego konta. Nie obchodzimy ograniczen serwisu.
+- **Vimm**: adres `https://vimm.net/vault/NUMER` przechodzi do **eksperymentalnego** adaptera uruchamiajacego Chromium. Wykorzystywany jest tylko faktycznie widoczny i dostepny przycisk `Download`. Brak omijania CAPTCHA, DRM, niedostepnych gier, antybota, limitow, kolejek i robots.txt. Gdy Vimm zmieni strone lub odrzuci automatyczny dostep, pobieranie nie bedzie dzialalo. Postep pobierania w trybie Vimm nie jest dostepny w % az do konca. Vimm uzywa jednej sesji naraz. Mozesz wylaczyc adapter w `.env`: `ENABLE_VIMM_BROWSER=false`.
+- **Import lokalny**: skopiuj plik do `/xbox/imports/`, odswiez karte Import i dodaj zadanie.
+
+Nie obslugujemy bypassowania zabezpieczen ani pobierania tresci wycofanych z serwisu. Uzywaj tylko plikow, do ktorych masz prawo.
+
+## Przetwarzanie
+
+| Wejscie | Format XEX | Format GOD |
+|---|---|---|
+| `.iso` Xbox 360 | `xdvdfs unpack` | `iso2god` |
+| `.zip`, `.7z`, `.rar`, `.tar` zawierajace ISO | Rozpakuj, nastepnie XEX | Rozpakuj, nastepnie GOD |
+| Folder z `default.xex` spakowany w ZIP/7z | Kopia folderu | `xdvdfs pack`, potem `iso2god` |
+| Link magnet zawierajacy ISO | j.w. | j.w. |
+
+Archiwa wieloczesciowe: wybierz wszystkie czesci w **jednym** zadaniu (zakladka Archive.org), a nie osobno. Obsługiwane sa m.in. `.part1.rar`, `.7z.001`. Nie kazdy wariant kompresji RAR dziala w p7zip — wtedy zadanie zakonczy sie czytelnym bledem. Hasla do zaszyfrowanych archiwow nie sa obslugiwane.
+
+Dla XEX program sprawdza obecnosc `default.xex`. Dla GOD konwerter generuje katalogi TitleID/content type i pliki Data. Na dysku masz:
+
+```text
+/xbox/                            # katalog na hoscie VM
+  downloads/<JOB_ID>/             # pobrane ISO, archiwa i torrenty (kontener: /data/raw)
+  downloads/<JOB_ID>/*.part       # nieukonczone transfery HTTP
+  downloads/<JOB_ID>/*.part.segments/ # segmenty Archive.org do wznowienia
+  work/<JOB_ID>/                  # rozpakowywanie i ISO tymczasowe (kontener: /data/work)
+  work/tmp/                       # systemowe pliki tymczasowe (TMPDIR)
+  work/cache/                     # cache Chromium/narzedzi (XDG_CACHE_HOME)
+  ready/xex/<GRA>/                # wynik XEX
+  ready/god/<GRA>/                # wynik GOD
+  imports/                        # reczny import ISO lub archiwum
+  torrents/<JOB_ID>.torrent       # metadane do wznowienia
+  metadata/<PODGLAD_ID>/          # metadane magneta i engine.log
+  private/archive-session.json   # sesja Archive.org (0600)
+  logs/<JOB_ID>.log               # log konwersji
+  logs/<JOB_ID>.bt.log            # log BT
+  logs/<JOB_ID>.download.log      # log transferu Archive
+  bt/<JOB_ID>.json                # status klienta Go
+  aria2/                          # stan i sesje aria2
+  queue.sqlite3                   # kolejka i historia zadan
+```
+
+
+Na Xbox przez FTP skopiuj **zawartosc** folderu `Gra` do `Hdd1:/Games/Nazwa/` i uruchom `default.xex` (albo wykonaj skan biblioteki Aurora). Dla GOD skopiuj `Content/0000000000000000/...` do `Hdd1:/Content/0000000000000000/...` z zachowaniem struktury. Gry wielodyskowe moga wymagac osobnej konfiguracji w Aurora.
+
+## Przyspieszenie Internet Archive (HTTP Range)
+
+Nowe instalacje maja `ARCHIVE_CONNECTIONS=50` w `.env`. Przy aktualizacji istniejacego projektu dopisz lub zmien te ustawienie w `.env`, np.:
+
+```dotenv
+ARCHIVE_CONNECTIONS=50
+```
+
+Dozwolone jest **1-50**. `1` wylacza segmentowanie i ogranicza pobieranie do jednego pliku na raz. W zadaniu z 3 plikami przy limicie 50 przydzial wyniesie np. **17 + 17 + 16 polaczen**. Kazdy plik zaczyna sie pobierac od razu; kolejne pliki (pow. 50) uruchamiaja sie w zwolnionych slotach. Przydzial na plik jest ustalany na poczatku danej grupy plikow; gdy plik sie skonczy, pozostale zachowuja swoje segmenty i przydzielone sloty, a wolny slot moze rozpoczac nastepny plik. Mniejsze pliki oraz wczesniej podzielone na 8 segmentow moga wykorzystac mniej polaczen. Jesli Archive.org odrzuca zadania (np. HTTP 429) albo transfer zwalnia, ogranicz liczbe np. do 8, 16 lub 24. Po zmianie wykonaj `docker compose up -d --build`. Panel pokazuje liczbe plikow aktywnych, zbiorczy postep i sumaryczna predkosc, a w `/xbox/logs/<JOB_ID>.download.log` zapisany jest przydzial polaczen i bledy kazdego pliku.
+
+Segmenty uruchamiaja sie tylko dla plikow dostatecznie duzych (co najmniej dwa zakresy po 8 MiB; 50 segmentow wymaga minimum 400 MiB pozostalych do pobrania), po potwierdzeniu obslugi `HTTP 206 Content-Range` przez serwer. Program nie omija ograniczen konta ani zabezpieczen serwisu. Gdy Archive.org ogranicza polaczenia (np. `HTTP 429`) aplikacja uwzglednia `Retry-After` w sekundach; obniz `ARCHIVE_CONNECTIONS`, jezeli problem sie powtarza.
+
+Zadania, ktore maja juz zapisane segmenty z poprzedniej wersji, zachowuja pierwotna liczbe segmentow, aby mozna je bylo bezpiecznie wznowic. Po aktualizacji rownolegle rusza takze pobieranie pozostalych plikow z tego samego zadania. Nie trzeba kasowac pobranych czesci. Aby zastosowac nowy podzial 50 do juz podzielonego pliku, trzeba utworzyc nowe zadanie. Aktualizacja nie nadpisuje istniejacego `.env`: po podmianie projektu ustaw tam `ARCHIVE_CONNECTIONS=50` i zrestartuj kontener.
+
+**Dysk:** przed konwersja potrzebne jest miejsce na segmenty i kolejna pelna kopie skladanego pliku. Sprawdz wolne miejsce w VM, zwlaszcza przy obrazach ISO po kilka GB.
+
+## Eksploatacja
+
+Aplikacja przechowuje kolejke SQLite, ma wznowienia HTTP i BitTorrent, jednego workera kolejki, do trzech podgladow magnet i przyciski stop/wznow/ponow. Wszystkie dane sa na hoscie w `/xbox` (domyslnie, bez wolumenow anonimowych), wiec pozostaja po restarcie kontenera. Zmiana lokalizacji jest mozliwa przez `XBOX_HOST_DIR` w `.env`. aria2 obsluguje zwykle linki HTTP/HTTPS, natomiast Go obsluguje magnety i pliki torrent. Czesciowo pobrane bloki torrenta sa weryfikowane po restarcie; Archive.org wznawia przez `.part` oraz katalog `.part.segments/` z oddzielnymi zakresami. Podczas koncowego laczenia czesci moze byc potrzebne dodatkowe miejsce na **jedna pelna kopie pliku**. Po poprawnym scaleniu czesci tymczasowe sa usuwane.
+
+**Bezpieczenstwo:** panel uzywa HTTP Basic Auth (haslo przesylane przy kazdym zadaniu HTTP). Formularz Archive.org rowniez przesyla haslo do lokalnego serwera. Zabezpiecz panel przed logowaniem poprzez HTTPS lub VPN; w lokalnym kontenerze haslo IA jest tylko przekazywane do `https://archive.org/services/xauthn/?op=login` i nie jest zapisywane. Sesja jest przechowywana w `/xbox/private` z uprawnieniami 0700/0600. Nie umieszczaj `/xbox/private` w publicznych kopiach projektu. Nie wystawiaj `8088` bezposrednio do internetu. Do dostepu z zewnatrz uzyj VPN (np. WireGuard/Tailscale) albo reverse proxy z TLS. Domyslnie port nasluchuje na LAN (`WEB_BIND=0.0.0.0`); aby ograniczyc dostep do maszyny lokalnej, ustaw `WEB_BIND=127.0.0.1` w `.env` i wykonaj `docker compose up -d`.
+
+## Ograniczenia obecnej wersji
+
+- Brak bezposredniego FTP do konsoli i automatycznego rozpoznawania wszystkich wielodyskowych instalacji.
+- Brak wyszukiwarki gier — podajesz wlasne URL/magnet/item Archive.
+- Nie kazde konto Archive.org ma dostep do kazdego elementu. Nie ma gwarancji logowania, gdy serwis zmieni xauthn lub wymaga dodatkowej weryfikacji. Duzy transfer z Archive.org jest wielopolaczeniowy, jesli serwer akceptuje Range. Wieksza liczba polaczen nie gwarantuje wzrostu predkosci; zalezy to od serwera, trasy sieciowej i limitow konta. Jesli pojawiaja sie HTTP 429 albo 503, zmniejsz liczbe polaczen. Powtarzajacy sie HTTP 500 po 5 probach nadal oznacza blad po stronie serwera lub dostepu do pliku.
+- Odczyt metadanych magneta wymaga dostepnych peerow. Jezeli liczba polaczen i znanych peerow pozostaje 0, sprawdz DHT/UDP lub uzyj pliku .torrent. Plik .torrent eliminuje czekanie na metadane, ale nie gwarantuje dostepnosci zawartosci. Brak dostepnych peerow oznacza, ze zadne ustawienie interfejsu nie gwarantuje pobrania metadanych. Limit podgladu: 5 min.
+- W Docker Compose sa mapowane porty BitTorrent 6881/tcp i 6881/udp. Jezeli inna aplikacja uzywa 6881 na hoście, ustaw `BT_PORT=16881` w `.env` i przebuduj kontener. Przy NAT wirtualki moze byc potrzebne przekierowanie portow w hypervisorze/routerze. DHT wymaga dzialajacego ruchu UDP.
+- Brak gwarancji dla stron wymagajacych JS/autoryzacji poza obslugiwanymi integracjami; sam aria2 nie imituje przegladarki.
+- Uwaga na miejsce: w najgorszym przypadku podczas rozpakowania i konwersji potrzeba **2–4x** rozmiaru ISO.
+- Nie testowano pobierania rzeczywistych plikow z Archive.org na prywatnym koncie, odzyskiwania wskazanego magneta z DHT ani konwersji realnego ISO w tym srodowisku. Testy API, sesji, HTTP Range, ponawiania HTTP 500, nadzorcy klienta Go, parsera torrenta i kolejki mozna uruchomic `PYTHONPATH=. pytest -q` z zaleznosciami z requirements i pytest. Nie przetestowano obrazu Dockera ani transferu na zywej sieci; wymagaja testu na VM.
+
+## Licencje i projekty
+
+Backend projektu: kod dostarczony tutaj. Zaleznosci i narzedzia sa instalowane niezaleznie na zasadach ich licencji: [aria2](https://aria2.github.io/), [anacrolix/torrent](https://github.com/anacrolix/torrent), [xdvdfs](https://github.com/antangelo/xdvdfs), [iso2god-rs](https://github.com/iliazeus/iso2god-rs), [Playwright](https://playwright.dev/), [FastAPI](https://fastapi.tiangolo.com/).
+
+## Diagnostyka: magnet / torrent / Archive.org
+
+Po aktualizacji najpierw uruchom nowe zadanie `.torrent` lub magnet. Stare zadania moga miec zapisane `gid` aria2; nowszy backend przy pierwszym uruchomieniu zatrzymuje ich transfery. W razie bledu nacisnij **Log** w panelu, a dodatkowo sprawdz:
+
+```bash
+docker compose ps
+docker compose logs --tail=120 x360-web
+# podstaw odpowiedni ID zadania z panelu lub katalogu /xbox/logs:
+ls -lt /xbox/logs/*.bt.log /xbox/logs/*.download.log 2>/dev/null | head
+# dla metadanych magnet: /xbox/metadata/<ID>/engine.log
+```
+
+Oczekiwanie na metadane z 0 peerow oznacza brak osiagalnego zrodla w danym momencie lub problem z siecia BT w VM. Wczytanie `.torrent` omija wyłącznie etap metadanych, a nie potrzebe aktywnych peerow. Go używa TCP/UDP; sprawdz DNS i wyjscie UDP w wirtualce. Przy NAT czasem przydaje sie przekierowanie `BT_PORT` przez hypervisor i router.
+
+Archive.org **nie uzywa juz aria2** do plikow z `/download/`. Pliki jednego zadania ida rownolegle z lacznym limitem 1-50 polaczen HTTP (domyslnie 50), a HTTP 500 jest ponawiany maksymalnie 5 razy na probe/segment. Jesli nadal dostaniesz HTTP 500, oznacza to odpowiedz Archive.org lub posredniego serwera, nie samego panelu. Log pokazuje kazda probe, bez sesyjnych ciasteczek.
+
+## Dane na dysku hosta: `/xbox`
+
+Compose montuje fizyczny katalog `/xbox` do `/data` w kontenerze. Dodatkowo
+`/xbox/downloads` jest montowany do `/data/raw`, dzieki czemu wszystkie stare
+sciezki w kolejce i sesjach aria2 pozostaja zgodne. Rowniez rozpakowywanie,
+konwersja i katalog tymczasowy (`TMPDIR`) korzystaja z tego samego katalogu
+hosta, a wynik trafia do `/xbox/ready/`. Nic z pobranych danych nie zalezy
+od dysku zapisywalnego kontenera.
+
+**Przed uruchomieniem musi istniec `/xbox`**. Jesli to podmontowany dysk
+lub udzial hosta, najpierw upewnij sie, ze jest dostepny i zapisywalny.
+Compose uzywa `bind.create_host_path: false`, zeby nie tworzyc po cichu
+brakujacej sciezki. **Jesli `/xbox` istnieje jako zwykly katalog pod
+niezamontowanym dyskiem, Compose nie rozpozna tego bledu** — w takim
+wypadku sprawdz `mountpoint /xbox` przed uruchomieniem.
+
+Przy nowej instalacji (jezeli katalog nie istnieje, utworz go najpierw):
+
+```bash
+sudo mkdir -p /xbox
+# Tylko dla nowego katalogu na lokalnym dysku (nie zmieniaj wlasciciela udzialu SMB/NFS):
+sudo chown "$(id -un):$(id -gn)" /xbox
+# Dla udzialu/montowanego dysku zapewnij uprawnienia zapisu innym sposobem.
+cd x360-web-queue
+./setup.sh
+```
+
+Jesli wolisz inna sciezke, dopisz do `.env` `XBOX_HOST_DIR=/sciezka/bezwzgledna`.
+Program nie zapisuje wtedy nic do `/xbox`, tylko do wybranej sciezki.
+Zmiana katalogu **nie przenosi** danych automatycznie.
+
+### Aktualizacja istniejacej instalacji (migracja `./data`)
+
+Zachowaj `.env` i `./data` przed wypakowaniem tej wersji. Rozpakuj ZIP w
+katalogu nadrzednym starego `x360-web-queue/` i wykonaj:
+
+```bash
+cd x360-web-queue
+# Upewnij sie, ze /xbox jest zamontowany i ma miejsce na dotychczasowe dane.
+./migrate-to-xbox.sh
+docker compose up -d --build
+```
+
+Skrypt zatrzymuje stary kontener **przed kopiowaniem**, przenosi przez kopiowanie
+katalog `./data/raw/` do `/xbox/downloads/` oraz reszte `./data/` do `/xbox/`.
+**Nie usuwa starego `./data` ani nie nadpisuje istniejacej bazy / plikow**.
+Przerwana migracje mozna ponowic, o ile nie zostala uruchomiona nowa instancja.
+Jezeli brakuje `rsync`, zainstaluj go (`sudo apt install rsync`).
+Po sprawdzeniu dzialania i kompletności pobranych plikow mozesz samodzielnie
+usunac stary `./data`, zwalniajac miejsce.
+
+Weryfikacja:
+
+```bash
+docker compose ps
+docker compose exec x360-web sh -c 'df -h /data/raw /data/work /data/ready; ls -ld /data/raw /data/work /data/ready'
+ls -lah /xbox/downloads /xbox/work /xbox/ready
+```
+
+**Uwaga:** dla SQLite i wznawiania pobierania najlepiej uzywac lokalnego
+systemu plikow z poprawnym blokowaniem (np. ext4 lub XFS). Przy montowaniu
+SMB/NFS sprawdz blokowanie plikow, uprawnienia i stabilnosc udzialu.