Új Indexerek integrálása

A StremHU Source egy moduláris indexer architektúrával rendelkezik. Ha egy új torrent oldalt szeretnél bekötni, saját indexer definíciót kell létrehoznod, ami a BaseIndexerDefinition osztályból öröklődik.

Hol helyezzük el az új indexert?

Minden új integrációt a szerver kódbázisában az app/modules/indexer_definitions/integrations mappában kell létrehozni, egy új .py fájlként. A rendszer automatikusan beolvassa a mappában lévő fájlokat, így nincs szükség manuális regisztrációra vagy importálásra.

A BaseIndexerDefinition osztály

A BaseIndexerDefinition (helye: app/modules/indexer_definitions/base_indexer_definition.py) számos absztrakt tulajdonságot és metódust vár el, melyeket a leszármazott osztályban meg kell valósítanod.

Az osztály belsőleg egy _client változón keresztül biztosít egy aszinkron HTTP klienst (httpx.AsyncClient alapokon), amely automatikusan kezeli a concurrency (párhuzamosság) korlátokat, a cookie-kat, az automatikus újra-bejelentkezéseket és az egyedi fejléceket. Kéréseket a self._client.get() vagy self._client.post() metódusokon keresztül érdemes indítanod.

Absztrakt tulajdonságok (Properties)

Az alábbi tulajdonságokat mindenképpen meg kell adnod az új indexerben:

• id (str): Az indexer egyedi azonosítója (pl. "ncore", "bithumen"). Ezzel hivatkozunk rá az adatbázisban és a hitelesítő adatok tárolásakor.
• name (str): A megjelenített név a felületen (pl. "nCore").
• url (str): Az oldal alap URL-je (pl. "https://ncore.pro").
• login_path (str): A bejelentkezési útvonal (pl. "/login.php").
• details_path (str): A torrent adatlap útvonala, "{torrent_id}" helyettesítővel (pl. "/torrents.php?action=details&id={torrent_id}").
• requires_full_download (bool): True, ha a torrent oldal a HnR (Hit and Run) teljesítésénél elvárja a teljes torrent letöltését, False, ha a részleges letöltés is elfogadott.

(Opcionális: A disabled property alapból False, ezt felülírhatod True-ra, ha az indexert ideiglenesen inaktiválni szeretnéd.)

Absztrakt metódusok (Üzleti logika)

A valós funkciókat az alábbi metódusok implementálásával kell biztosítani:

1. _detect_authentication_error(self, response: httpx.Response) -> AuthenticationErrorEnum | None

Itt kell meghatározni, hogy egy normál HTTP kérés válasza alapján történt-e munkamenet (session) hiba, vagy hibás hitelesítő adatokkal próbáltunk belépni. Visszatérési értékek:

• AuthenticationErrorEnum.CREDENTIAL_ERROR: Ha a bejelentkezés egyértelműen meghiúsult (pl. rossz felhasználónév/jelszó miatt).
• AuthenticationErrorEnum.SESSION_ERROR: Ha az oldal például visszairányított (redirect) a bejelentkezési oldalra egy normál lekérdezés során, ami lejárt session-t jelent.
• None: Ha nincsenek hitelesítési problémák.

2. _login(self, credential: IndexerDefinitionLogin) -> httpx.Response

Ez a metódus végzi el a tényleges POST kérést a hitelesítő adatokkal. Nem kell manuálisan kezelni a cookie-kat, a belső HTTP kliens megőrzi azokat a sikeres válaszból. Példa:

async def _login(self, credential: IndexerDefinitionLogin) -> httpx.Response:
    return await self._client.post(
        self.login_path,
        data={"nev": credential.username, "pass": credential.password},
        headers={"Content-Type": "application/x-www-form-urlencoded"},
    )

3. _fetch_torrents(self, imdb_id: str, page: int | None = None) -> IndexerDefinitionFindTorrentsResult

A keresés megvalósítása IMDB azonosító (imdb_id) alapján. A metódusnak egy IndexerDefinitionFindTorrentsResult objektummal kell visszatérnie, ami tartalmazza a talált torrentek listáját (torrents) és a következő oldal számát (next_page), vagy None-t, ha nincs több oldal. A weboldal lekaparásához (scraping) a StremHU a selectolax.parser.HTMLParser modult használja a HTML DOM villámgyors feldolgozására, kivéve ha az indexer rendelkezik egy JSON alapú API végponttal.

4. _fetch_torrent(self, torrent_id: str) -> IndexerDefinitionTorrent | None

Egy konkrét torrent részleteinek és legfőképpen a pontos letöltési URL-jének bekérése az azonosító alapján. Ha a torrent esetleg már nem található (törölték), biztonságosan térjen vissza None értékkel.

5. _fetch_hit_and_run_ids(self) -> list[str]

Lekéri a kötelezően seedelendő (Hit & Run) torrentek azonosítóinak listáját a felhasználó profiljából. Fontos a belső figyelmeztetési / seedelési automatizmusokhoz.

Példa egy alap struktúrára

import httpx
from selectolax.parser import HTMLParser
 
from app.modules.indexer_definitions.base_indexer_definition import BaseIndexerDefinition
from app.modules.indexer_definitions.enums import AuthenticationErrorEnum
from app.modules.indexer_definitions.schemas.internal import (
    IndexerDefinitionFindTorrentsResult,
    IndexerDefinitionLogin,
    IndexerDefinitionTorrent,
)
 
class MyCustomIndexerDefinition(BaseIndexerDefinition):
    @property
    def id(self) -> str:
        return "my_custom_indexer"
 
    @property
    def name(self) -> str:
        return "MyCustomIndexer"
 
    @property
    def url(self) -> str:
        return "https://my-custom-indexer.com"
 
    @property
    def login_path(self) -> str:
        return "/login.php"
 
    @property
    def details_path(self) -> str:
        return "/details.php?id={torrent_id}"
 
    @property
    def requires_full_download(self) -> bool:
        return True
 
    def _detect_authentication_error(self, response: httpx.Response) -> AuthenticationErrorEnum | None:
        # Hibakeresési logika implementációja
        return None
 
    async def _login(self, credential: IndexerDefinitionLogin) -> httpx.Response:
        # Belépési POST kérés
        pass
 
    async def _fetch_torrents(self, imdb_id: str, page: int | None = None) -> IndexerDefinitionFindTorrentsResult:
        # Keresési logika (DOM feldolgozás vagy API hívás)
        pass
 
    async def _fetch_torrent(self, torrent_id: str) -> IndexerDefinitionTorrent | None:
        # Konkrét torrent letöltési URL megkeresése
        pass
 
    async def _fetch_hit_and_run_ids(self) -> list[str]:
        # Hit n Run lista kinyerése
        pass

Hasznos tippek fejlesztőknek

• Párhuzamosítás korlátozása (Concurrency): A belső _client automatikusan szemaforokkal (alapértelmezés szerint max. 5 egyidejű lekérdezéssel) szabályozza a kérések számát a szerver túlterhelésének elkerülése végett (a max_concurrent property felülírásával ez az érték módosítható).
• Automatikus Session Frissítés: A keretrendszer beépített újrapróbálkozási mechanizmussal rendelkezik. Ha a _detect_authentication_error egy API kérés után SESSION_ERROR hibát detektál, az alkalmazás a háttérben automatikusan újrahitelesíti a fiókot, majd probléma mentesen megismétli az elakadt kérést.
• Letöltés lebonyolítása: A .torrent fájl fizikai letöltését vagy feldolgozását is a beépített bázis kliens végzi (ezt a download_torrent metódus fedi a BaseIndexerDefinition-ben), így integrátorként a te dolgod mindössze az, hogy a kinyert download_url-t megadd a visszatérési modellben (IndexerDefinitionTorrent).