API serwera Calibre — zanotowano
Dokumentacja techniczna i projekt. W dokumencie tym zachowane są studia i przewidziana architektura. Nie wszystkie opisane funkcje mogą być dostępne; the instrukcja obsługi i kod określają bieżącą operację.
Oświadczenie złożone 30 października 2026 roku na podstawie kodu źródłowego Calibre (src/calibre/srv/), brak dokumentacji: żadna nie istnieje. Wdrożono i objęto testami w Packages/Core/Sources/CalibreKit.
1. Ostrzeżenie, które pochodzi od samego konserwatora
Zapytany o dokumentację dla API /ajax, Kovid Goyal odpowiada, że nie istnieje, że tej powierzchni nie ma ani publiczny, ani stabilny i że trzeba przeczytać źródło. Konsekwencje zachowane w CalibreKit :
- całe dekodowanie jest tolerowane — zaginiony, nieoczekiwany lub
nullnigdy nie powoduje niepowodzenia wyświetlania listy bibliotek; - Po połączeniu wykrywany jest charakter serwera (
detectFlavor()), ponieważ Calibre-Web odpowiada na wszystko na 404/ajax/*i oferuje tylko OPDS; - OPDS pozostaje trasą awaryjną, znormalizowany i stabilny;
- Testy zamrażają rzeczywiste kształty bajtów, więc aktualizacja Calibre powoduje przerwanie testu, a nie aplikacji.
2. Trzy konwencje nazewnictwa biblioteki
To jest główna pułapka tego API. Jest kodowany raz CalibreClient.url(path:query:libraryInQuery:) i zweryfikowany czterema testami.
| Rodzina tras | Dokąd zmierza library_id |
|---|---|
/ajax/…, /get/… | komponent ścieżki — /ajax/search/Calibre_Library |
/conversion/…, /cdb/…, /fts/… | parametr zapytania — ?library_id=Calibre_Library |
/book-…-last-read-position/… | komponent ścieżki, ponownie |
Zameldowałem się srv/utils.py : get_library_data() łóżko rd.query.get('library_id').
3. Katalog — srv/ajax.py
| Droga | Zwroty |
|---|---|
GET /ajax/library-info | {library_map, default_library} — służy również jako test natury serwera |
GET /ajax/search/{library} | {total_num, offset, num, book_ids, …}, parametry query, num, offset, sort, sort_order, vl |
GET /ajax/books/{library}?ids=1,2,3 | słownik indeksowane według identyfikatora, null dla zakazanej książki |
GET /ajax/book/{id}/{library} | metadane książki |
GET /ajax/categories/{library} | kategorie pierwszego poziomu |
GET /ajax/category/{nom}/{library} | zawartość kategorii, spaginowana |
GET /ajax/books_in/{cat}/{item}/{library} | identyfikatory kategorii |
Dwie pułapki w dekodowaniu, obie objęte testami:
Identyfikatora nie ma w temacie. /ajax/books indeksuje swój słownik według identyfikatora i nie powtarza go w środku. CalibreKit wstrzykuje go przez userInfo dekodera.
0101-01-01T00:00:00+00:00 oznacza „brak daty”. To wartownik UNDEFINED_DATE z Calibre. Naiwnie odszyfrowane, tworzy książkę opublikowaną w starożytności. CalibreDate przywraca to nil.
4. Konwersja — srv/convert.py
To odkrycie zmienia architekturę: serwer Calibre dokonuje konwersji poprzez HTTP.
| Droga | Metoda | Rola |
|---|---|---|
/conversion/book-data/{id} | POBIERZ | formaty wejściowe, formaty wyjściowe, akceptowane opcje |
/conversion/start/{id} | POST | ciało {input_fmt, output_fmt, options} → zwraca identyfikator zadania |
/conversion/status/{job} | POST | {running, percent, msg} następnie stan końcowy; ?abort_job=1 przerywa |
Szczegóły podane w źródle i wszystkie istotne w użyciu:
- Tylko POST (
receive_data_methods = {'POST'}). GET zostaje odrzucony. input_fmtmusi być format, jaki faktycznie ma ta książka : Serwer buduje stamtąd ścieżkę źródłową i odrzuca resztę. Czeka na to wielkimi literami,output_fmtmałymi literami.- Status jest zużywany przy pierwszym odczycie terminala :
del conversion_jobs[job_id], zatemcleanup()wfinally. Konkluzję możesz przeczytać tylko raz. I tylko użytkownik, który uruchomił zadanie w tej samej bibliotece, może wysyłać do niego zapytania.CalibreKit.convert(…)otacza pętlę sondującą, więc żaden rozmówca nie musi o tym myśleć. - Format produktu został dodany do książki w bibliotece :
db.add_format(book_id, fmt, output_path). Praca jest zatem wykonywana tylko raz, a następnie wszystkie urządzenia z niej korzystają./get/EPUB/{id}. - Pliki receptur są odrzucane (wykonanie kodu), a lista opcji jest blokowana przez sieć.
Pełna trasa, np CalibreKit implementuje to:
GET /conversion/book-data/42?library_id=L → entrées : AZW3, PDF ; sorties : epub, mobi, …
POST /conversion/start/42?library_id=L → 17
{"input_fmt":"AZW3","output_fmt":"epub","options":{}}
POST /conversion/status/17?library_id=L → {"running":true,"percent":10,"msg":"Lecture"}
POST /conversion/status/17?library_id=L → {"running":false,"ok":true,"fmt":"epub","size":912345}
GET /get/EPUB/42/L → le fichier, désormais dans la bibliothèque
5. Pozycja odczytu i adnotacje — srv/books.py
Calibre już synchronizuje pozycje odtwarzania po stronie serwera.
| Droga | Metoda | Rola |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | POBIERZ | znane pozycje według urządzenia |
/book-set-last-read-position/{library}/{id}/{FMT} | POST | zapisuje {device, cfi, pos, pos_frac} |
/book-get-annotations/{library}/{which} | POBIERZ | podkreślenia i notatki |
/book-manifest/{id}/{FMT} | POBIERZ | Serwer normalizuje dowolny format w manifeście dla własnego czytelnika |
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom} | POBIERZ | ujednolicony zasób książkowy |
/book-get-storage/{library}/{id}/{FMT} | POBIERZ | stan przechowywania |
Dwie konsekwencje dla Podbook:
Możemy porzucić gazety .jsonl opisany w początkowej specyfikacji, przynajmniej jako główny mechanizm: Calibre już utrzymuje pozycję na urządzenie, na książkę i na format. Dzienniki są nadal przydatne w przypadku tego, czego Calibre nie wie – pozycji w nagraniu, notesu ze słownictwem.
/book-manifest to skrót do oceny. Serwer już wie, jak przekształcić dowolny format w standardową strukturę dla swojego czytnika internetowego. Obejmuje to część tego, co BookKit musiało wystarczyć. Należy sprawdzić przed napisaniem parsera: format manifestu jest wewnętrzny dla Calibre, dlatego należy go traktować jako powierzchnię /ajax, zachowując ostrożność.
srv/kosync.py dodatkowo udostępnia protokół synchronizacji KOReader (/kosync/users/auth, /kosync/syncs/progress), kolejna możliwa trasa, przyjęta już przez innych czytelników.
6. Wyszukiwanie pełnotekstowe — srv/fts.py
| Droga | Metoda | Rola |
|---|---|---|
/fts/search | POBIERZ | szukaj w tekście ksiąg, nie tylko metadane |
/fts/snippets/{book_ids} | POBIERZ | fragmenty z kontekstem |
/fts/reindex, /fts/indexing, /fts/disable | POST | kontrola indeksu |
Indeks musi być włączony po stronie serwera. Dlatego Podbook nie musi indeksować samej biblioteki w celu wyszukiwania globalnego — tylko dla książek importowanych spoza Calibre.
7. Pisanie w bibliotece — srv/cdb.py
POST /cdb/cmd/{commande}?library_id=L wykonuje podkomendę calibredb na serwerze. To jest Tam obsługiwany sposób zapisu: metadata.db nie toleruje drugiego redaktora.
Dostępne polecenia: add, add_format, remove, remove_format, set_metadata, set_custom, add_custom_column, remove_custom_column, custom_columns, annotations, search, list, list_categories, items, notes, data_files, embed_metadata, export, catalog, saved_searches, virtual_libraries, fts_index, fts_search, check_library, backup_metadata, restore_database, clone, trash.
set_custom umożliwia zapisanie statusu przetwarzania Podbook w niestandardowej kolumnie #podbook, widoczne z Calibre, prawidłowo.
8. OPDS — srv/opds.py
/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Standard, stabilny, ogłoszony w Hello w sieci lokalnej. To wycofanie, kiedy /ajax tam nie ma — zwłaszcza przeciwko Calibre-Web.
9. Co to zmienia dla Podbook
| Hipoteza wstępna | Rzeczywistość |
|---|---|
| Należy napisać parser MOBI | Fałsz z wersji 1: ebook-convert już wystarczyło |
| Konwersja wymaga warsztatu na temat Mac | Fałsz : calibre-server konwertuje na HTTP. iPad żądań, serwer działa, biblioteka jest wzbogacona |
| Podbook musi wymyślić synchronizację swojej pozycji | Częściowo fałszywe : Calibre już zawiera jeden na każde urządzenie |
| Podbook powinno indeksować w wyszukiwaniu globalnym | Fałsz : /fts/search istnieje |
metadata.db tylko do odczytu, brak możliwości zapisu | Fałsz : /cdb/cmd/… to oficjalna trasa pisania |
API /ajax to solidny fundament | Fałsz : niepubliczny i niestabilny. Stąd tolerancyjne dekodowanie, wykrywanie natury i powrót OPDS |
Nadal prawda: pliki chronione DRM nie zostaną otwarte, a serwer Calibre musi gdzieś działać, aby możliwa była konwersja i wyszukiwanie globalne.