Client OPDS per Calibre Web (Sailfish OS): core C++ testato, UI Silica, packaging RPM

2026-08-12 01:45:31 +02:00
commit 85b4f8e9b9
25 changed files with 1518 additions and 0 deletions
@@ -0,0 +1,99 @@
+# harbour-calibreweb
+
+Client **OPDS** per Sailfish OS: naviga e scarica libri dalla tua istanza
+**Calibre Web** (o dal Content Server di Calibre).
+
+Funziona con qualsiasi server OPDS, ma è pensato per Calibre Web:
+feed di navigazione, ricerca, copertine, download con progresso.
+
+## Perché OPDS e non l'API REST
+
+Le versioni recenti di calibre-web (upstream) **non hanno più l'API REST**:
+`/api/*` è stata rimossa e non esiste in nessuna release 0.6.9+ né in master.
+L'interfaccia stabile e documentata è **OPDS** (`/opds`, `/opds/new`,
+`/opds/search?query=...`), che usa HTTP Basic Auth ed espone i link di
+download per formato. OPDS è supportato anche dal Content Server di Calibre,
+quindi questa app copre entrambi i backend.
+
+## Funzionalità
+
+- Sezioni del catalogo (novità, autori, categorie, scaffali, ...) dall'indice `/opds`
+- Paginazione automatica (link `rel="next"`)
+- Ricerca testuale (`/opds/search`)
+- Copertine con cache locale
+- Dettaglio libro: autore, descrizione, formati con dimensione
+- Download con barra di progresso in `~/Downloads`
+- Autenticazione HTTP Basic (utente vuoto = browse anonimo)
+- Opzione "ignora errori SSL" per certificati autofirmati
+
+## Build
+
+Serve il [Sailfish SDK](https://sailfishos.org/wiki/Sailfish_SDK)
+(su Linux: `flatpak install flathub org.sailfishos.sdk` o tarball).
+
+```sh
+git clone <questo repo> harbour-calibreweb
+cd harbour-calibreweb
+
+# scegli un target, es.:
+sfdk target install SailfishOS-4.6.0.11-armv7hl
+sfdk target use SailfishOS-4.6.0.11-armv7hl
+
+sfdk build                 # produce l'RPM in RPMS/
+sfdk deploy                # installa sul dispositivo connesso
+```
+
+In alternativa, installa l'RPM a mano:
+
+```sh
+pkcon install-local harbour-calibreweb-0.1.0-1.armv7hl.rpm
+```
+
+Target consigliati in base al dispositivo: `armv7hl` (Xperia X, Jolla C…),
+`aarch64` (Xperia 10 II/III, Jolla C2), `x86_64` (emulatore).
+
+## Configurazione
+
+Apri l'app → menù → **Impostazioni**:
+
+| Campo | Valore |
+|---|---|
+| Indirizzo Calibre Web | es. `https://calibre.example.com` (o con sottopath) |
+| Utente | vuoto se il browse anonimo è attivo su calibre-web |
+| Password | quella dell'account (Basic Auth) |
+| Ignora SSL | attivalo solo se il server ha un certificato autofirmato |
+
+Poi **Prova connessione** e naviga.
+
+## Struttura
+
+```
+src/                C++: settings (QSettings), apiclient (feed+copertine),
+                    downloader (progressi), opdsparser (Atom/OPDS), main
+qml/pages/          MainPage (indice), FeedPage (liste+paginazione),
+                    BookDetailPage (dettaglio+download), SearchPage, SettingsPage
+qml/cover/          cover dell'app
+icons/              icone 86/108 px + script di generazione
+rpm/                spec e desktop file
+```
+
+## Limiti noti
+
+- La password è salvata in chiaro nelle impostazioni dell'app
+  (`~/.config/harbour/calibreweb.conf`) — accettabile per uso personale.
+- La ricerca usa il motore del server; risultati identici alla UI web.
+- Il core C++ (parsing, auth, download) è testato con Qt 5.15 contro feed
+  OPDS reali e un mock con Basic Auth; la UI Silica richiede il SDK per
+  la verifica su dispositivo.
+
+## Test del core
+
+```sh
+# mock server OPDS + test end-to-end (vedi repository /tmp in locale):
+python3 /tmp/mock_opds.py
+# compila e lancia /tmp/opds_test (Qt 5.15+)
+```
+
+## Licenza
+
+MIT