Writing to OPDS library file by hamazaspavetisyan · Pull Request #1321 · kiwix/libkiwix

hamazaspavetisyan · 2026-08-06T22:47:59Z

Writing an OPDS library file

Why

Continues #1319 toward #1309's goal of dropping library.xml in favor of OPDS. #1319 added OPDS reading; this PR adds writing, so a library can round-trip through OPDS alone.

What

Added LibOPDSDumper (mirrors LibXMLDumper) to dump a Library to an OPDS document for local/offline use, and Library::writeToOPDSFile(path) to write it. writeToFile() is now a deprecated alias for a new writeToXMLFile().
fullEntryOpds() gains an optional selfPath param, rendered as a rel="self" link to the book's local path — used only by LibOPDSDumper, never by the live HTTP OPDSDumper, to avoid leaking server filesystem paths.
The rel="search" link is now opt-in (include_search_link): still emitted for the live catalog (kiwix-serve), dropped for offline file dumps since there's no search endpoint to point at.
Dropped a dead friend class libXMLDumper; (case typo, never matched the real class).
Tests parameterized to cover both .xml and .opds round-trips.

Impact on libkiwix users/devs

No breaking API changes; writeToFile() still works as before. New writeToOPDSFile() lets callers persist a library as OPDS, readable back via Manager::readFile() (#1319) with no extra handling. kiwix-tools needs no changes.

Fundamental change

Library is no longer XML-only for serialization — OPDS output now covers both the live catalog and local file dumps through the same rendering path, differing only in what's safe to expose (paths, search links) per use case.

Notes

This PR builds on top of #1319 and should be reviewed/merged after it (this branch currently includes #1319's commits since it hasn't landed on main yet). Follow-up in kiwix-tools is expected — kiwix-manage and kiwix-serve.

codecov · 2026-08-06T23:14:08Z

Codecov Report

❌ Patch coverage is 40.90909% with 39 lines in your changes missing coverage. Please review.
✅ Project coverage is 43.61%. Comparing base (335eb12) to head (e8a4765).

Files with missing lines	Patch %	Lines
src/library.cpp	0.00%	15 Missing ⚠️
src/libopds_dumper.cpp	52.17%	3 Missing and 8 partials ⚠️
src/book.cpp	33.33%	0 Missing and 6 partials ⚠️
src/manager.cpp	60.00%	0 Missing and 6 partials ⚠️
src/library_dumper.cpp	0.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1321      +/-   ##
==========================================
+ Coverage   43.54%   43.61%   +0.06%     
==========================================
  Files          60       62       +2     
  Lines        4848     4907      +59     
  Branches     2547     2580      +33     
==========================================
+ Hits         2111     2140      +29     
- Misses       1085     1098      +13     
- Partials     1652     1669      +17

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…uire it

kelson42 · 2026-08-10T06:40:01Z

@hamazaspavetisyan AFAIK witting library.xml capacity is not fully dropped, right?

hamazaspavetisyan · 2026-08-10T06:47:12Z

@hamazaspavetisyan AFAIK witting library.xml capacity is not fully dropped, right?

Yes, as we discussed under previous PR, first we will have symmetric behavoiur for XML and ODPS, then will drop the XML.

veloman-yunkan

This was a quick superficial review. Take it with a grain of salt.

veloman-yunkan · 2026-08-10T08:23:58Z

+  std::string opds;
+  {
+    std::lock_guard<std::recursive_mutex> lock(m_mutex);
+    std::ostringstream oss;
+    dumper.dumpOPDSContent(allBookIds, oss);
+    opds = oss.str();
+  };
+  return writeTextFile(path, opds);


Why don't you write directly to a file via std::ofstream?

@veloman-yunkan
writeTextFile() isn't a plain ofstream wrapper — it opens the file via _wopen(Utf8ToWide(path), ...) on Windows so that UTF-8 library paths with non-ASCII characters work correctly (see pathTools.cpp:397). A raw std::ofstream(path) would go through the narrow-string/local-codepage path on Windows and break on those paths.

veloman-yunkan · 2026-08-10T08:44:08Z

+   * @param bookIds the ids of the books to include.
+   * @param os the output stream to write the OPDS content into.
+   */
+  void dumpOPDSContent(const std::vector<std::string>& bookIds, std::ostream& os);


I don't think that we need to filter the library when saving it.

@veloman-yunkan I mirrored this from dumpLibXMLContent, if we need symmetric behaviour, then having such argument is good idea

veloman-yunkan · 2026-08-10T08:48:50Z

+  /**
+   * Set the library to dump.
+   *
+   * @param library The library to dump.
+   */
+  void setLibrary(const Library* library) { this->library = library; }


I don't think we need this method. In fact I don't even think that we need a user-visible class for dumping a library. It looks like a free-function void dumpLibraryOpds(const Library& lib, const std::string& outputPath) is all we need as user facing API (where baseDir is derived from outputPath). Wait! Library::writeToOPDSFile() is that function. Why can't the OPDS export be implemented there directly? I guess, because we want that functionality to be unit testable. Then we can have void dumpLibraryOpds(const Library& lib, const std::string& baseDir, std::ostream& out) as a testable workhorse and the two-parameter version as a simple wrapper around it.

@veloman-yunkan I agree with you, we can remove LibOPDSDumper entirely and keep only writer method that will be called from Library::writeToOPDSFile. But again I prefer to have symmetric structure for XML and OPDS, then clean up codes in scope of separate issue. What you think ?

…om OPDS file

hamazaspavetisyan added 8 commits August 7, 2026 20:33

Added test cases for parseXmlDom()

dbf7ccd

Added test cases for parseOpdsDom()

e769b7a

Making parseOpdsDom() method also parse library files

8590eb8

Changing readFile() method, to support both XML and OPDS formats

f28a876

Reading static vim file path from OPDS library

11cceb6

Make the search link optional in OPDS dumps, as file dumps do not req…

93f0123

…uire it

Ability to dump OPDS with "path" support for

c2e0994

LibOPDSDumper class with its test case

486543e

hamazaspavetisyan force-pushed the issue-1309-write-opds branch from 0caeee1 to ef341c7 Compare August 7, 2026 18:08

hamazaspavetisyan requested a review from veloman-yunkan August 10, 2026 06:55

veloman-yunkan reviewed Aug 10, 2026

View reviewed changes

hamazaspavetisyan force-pushed the issue-1309-write-opds branch from ef341c7 to 57eb763 Compare August 10, 2026 13:03

hamazaspavetisyan added 6 commits August 10, 2026 17:47

Support writing the library as an OPDS document

8e9c791

Added a new test case for fullEntryOpdsTest() to cover path fields fr…

3e7ffc4

…om OPDS file

Parameterize LibForServerSearchTest to also search an OPDS library

1a7e810

Parameterize LibraryTest to cover also OPDS file loading

3929d26

Parameterize LibraryServerTest to cover also OPDS file loading

f3effdc

Parameterize ManagerTest to cover also OPDS file re-loading

e8a4765

hamazaspavetisyan force-pushed the issue-1309-write-opds branch from 57eb763 to e8a4765 Compare August 10, 2026 13:49

Navigation Menu

Uh oh!

Uh oh!

Writing to OPDS library file - #1321

Writing to OPDS library file#1321
hamazaspavetisyan wants to merge 14 commits into
mainfrom
issue-1309-write-opds

hamazaspavetisyan commented Aug 6, 2026

Uh oh!

codecov Bot commented Aug 6, 2026 •

edited

Loading

Uh oh!

kelson42 commented Aug 10, 2026

Uh oh!

hamazaspavetisyan commented Aug 10, 2026

Uh oh!

veloman-yunkan left a comment

Uh oh!

veloman-yunkan Aug 10, 2026

Uh oh!

hamazaspavetisyan Aug 10, 2026

Uh oh!

Uh oh!

veloman-yunkan Aug 10, 2026

Uh oh!

hamazaspavetisyan Aug 10, 2026 •

edited

Loading

Uh oh!

veloman-yunkan Aug 10, 2026

Uh oh!

hamazaspavetisyan Aug 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

hamazaspavetisyan commented Aug 6, 2026

Writing an OPDS library file

Why

What

Impact on libkiwix users/devs

Fundamental change

Notes

Uh oh!

codecov Bot commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

kelson42 commented Aug 10, 2026

Uh oh!

hamazaspavetisyan commented Aug 10, 2026

Uh oh!

veloman-yunkan left a comment

Choose a reason for hiding this comment

Uh oh!

veloman-yunkan Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

hamazaspavetisyan Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

veloman-yunkan Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

hamazaspavetisyan Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

veloman-yunkan Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

hamazaspavetisyan Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov Bot commented Aug 6, 2026 •

edited

Loading

hamazaspavetisyan Aug 10, 2026 •

edited

Loading