add stuff

README.md

@@ -4,8 +4,12 @@ das komplette serverjonas search
 
 - `crawler.py` – PostgreSQL-Crawler, baut den Suchindex auf
 - `launcher.py` – startet/überwacht den Crawler und rollt Updates aus (siehe unten)
-- `search/` – Suchmaschine darüber (CLI + HTTP-API), siehe [search/README.md](search/README.md)
-- `web/` – Statistik-Webseite
+- `search/` – Suchmaschine darüber (CLI + HTTP-API + Weboberfläche, Port 8083),
+  siehe [search/README.md](search/README.md)
+- `web/` – Statistik-Webseite (Port 8081, `jonassearch-stats.service`)
+- `priorityweb/` – Vorschlagsverfeinerer (Port 8082, `jonassearch-priority.service`)
+- `search/jonassearch-engine.service` – systemd-Unit für die Suchmaschine
+  (Port 8083, `jonassearch-engine.service`)
 - `fix_pages_search_vector_trigger.sql` – einmalig laufen lassen: kappelt den Text,
   der im DB-Trigger `pages_search_vector_update()` in `to_tsvector()` einfließt
   (Postgres hartes Limit: 1.048.575 Bytes pro `tsvector`)
@@ -38,6 +42,45 @@ Zusätzlich werden bekannt wertlose URLs (`pkg.go.dev/...?tab=importedby` –
 Megabyte-große reine Rückverweis-Listen) über `SKIP_URL_PATTERNS` schon vor dem
 Fetch übersprungen und als `done` markiert.
 
+## Domain-Switching / Block-Handling
+
+Der Crawler wartet nie auf einer langsamen oder blockierten Domain:
+
+1. **Claim mit Host-Check:** Beim Holen des nächsten Queue-Eintrags prüft der
+   Worker pro Kandidat (Prioritätsreihenfolge, bis zu
+   `JONASSEARCH_CLAIM_SCAN_LIMIT` Kandidaten), ob der Host gerade crawlbar ist
+   (Per-Host-Delay aus robots.txt bzw. `JONASSEARCH_DELAY`, aktive
+   Backoff-Sperre). Nicht crawlbare Hosts werden übersprungen – der Worker
+   arbeitet automatisch auf einer anderen Domain weiter und kehrt zurück,
+   sobald der Host wieder darf. Ist gerade gar kein Host crawlbar, schläft
+   der Worker bis zum frühesten freigegebenen Host (gekappet bei
+   `JONASSEARCH_MAX_IDLE_SLEEP`, dann wird neu gescannt).
+2. **Backoff bei Blocks:** HTTP 429/5xx/403/401 und Netzwerkfehler setzen den
+   Host auf exponentielles Backoff (z. B. 429: 60 s, sich verdoppelnd bis
+   30 min; 403/401: 10 min bis 2 h). Ein `Retry-After`-Header wird zusätzlich
+   beachtet. Bei einem erfolgreichen Fetch zählt der Zähler wieder von vorn.
+3. **Retry statt Verlust:** Transiente Fehler (429/5xx/Netzwerk) werden
+   wieder in die Queue gestellt (`pending`) statt endgültig `failed` –
+   begrenzt durch `JONASSEARCH_MAX_ATTEMPTS` (Standard 5), damit dauerhaft
+   kaputte Hosts nicht ewig rotieren. Wartezeiten größer als
+   `JONASSEARCH_MAX_INLINE_WAIT` (z. B. großer robots-crawl-delay) werden
+   nicht inline geschlafen: das Item wird ohne Versuchs-Zählung zurückgestellt
+   und solange eine andere Domain gecrawlt.
+
+## Nicht crawlbare Ziele (localhost, IPs, nicht-echte Domains)
+
+Der Crawler folgt nur echten, öffentlich auflösbaren Domains. Bereits in
+`normalize_url()` werden abgelehnt und nie in die Queue gestellt:
+
+- `localhost`, `*.localhost`, `localhost.localdomain`, `*.local`, `*.internal`
+- reine IP-Adressen als Host (IPv4 und IPv6, z. B. `127.0.0.1`, `http://[::1]/`)
+- Hostnamen ohne Punkt (Einzel-Labels wie `http://myserver/` – LAN-Namen)
+
+Alte Queue-Einträge mit solchen Hosts werden beim Zugriff als `done`
+markiert und nicht mehr geholt. Zeigt der Start-URL auf so einen Host,
+beendet sich der Crawler mit einem klaren Fehler (Exit 1) statt endlos
+zu rotieren.
+
 ## Rolling Updates (Generation-Mechanismus)
 
 Zentrale Tabelle (eine Zeile, `id = 1`):