hbkit 0.4.3__tar.gz → 0.4.5__tar.gz

{hbkit-0.4.3 → hbkit-0.4.5}/.gitignore

@@ -8,3 +8,6 @@ build/
 .pytest_cache/
 .DS_Store
 *.part
+
+# Local-only fixtures: hashes of source files that only exist on this machine.
+.local/

{hbkit-0.4.3 → hbkit-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hbkit
-Version: 0.4.3
+Version: 0.4.5
 Summary: Recover files from Synology Hyper Backup (.hbk) archives without Synology software
 Project-URL: Homepage, https://github.com/YordiLorenzo/hbkit
 Project-URL: Source, https://github.com/YordiLorenzo/hbkit
@@ -288,6 +288,8 @@ Read this before trusting it with the only copy of anything.
   bytes, which is the one thing a recovery tool must never do.
 - **Whole-file dedup** (`off_virtual_file = -1`, files living in `Pool/file_pool`) is not
   decoded. One file in 501,278 in the reference archive.
+- **Windows is untested for extraction.** CI installs the package and checks that it
+  imports, but no archive has been rebuilt on Windows. Linux and macOS are verified.
 
 ## The format
 

{hbkit-0.4.3 → hbkit-0.4.5}/README.md

@@ -259,6 +259,8 @@ Read this before trusting it with the only copy of anything.
   bytes, which is the one thing a recovery tool must never do.
 - **Whole-file dedup** (`off_virtual_file = -1`, files living in `Pool/file_pool`) is not
   decoded. One file in 501,278 in the reference archive.
+- **Windows is untested for extraction.** CI installs the package and checks that it
+  imports, but no archive has been rebuilt on Windows. Linux and macOS are verified.
 
 ## The format
 

{hbkit-0.4.3 → hbkit-0.4.5}/packaging/README.md

@@ -8,7 +8,7 @@ the hash, nothing else.
 | ------ | ---------- | -------- |
 | Homebrew | — | [YordiLorenzo/homebrew-tap](https://github.com/YordiLorenzo/homebrew-tap) |
 | AUR | `aur/PKGBUILD`, `aur/.SRCINFO` | `ssh://aur@aur.archlinux.org/hbkit.git` |
-| nixpkgs | `nix/package.nix` | `pkgs/by-name/hb/hbkit/package.nix` |
+| nixpkgs | `nix/package.nix` | `pkgs/by-name/hb/hbkit/package.nix` ([PR #550225](https://github.com/NixOS/nixpkgs/pull/550225)) |
 
 ## A note on liblz4
 
@@ -17,15 +17,21 @@ still builds and installs cleanly, then fails the first time someone extracts a
 recipe here must declare it, and should ideally set `HBK_LZ4` to an absolute path so the
 library resolves regardless of the loader search path.
 
-The Homebrew formula wraps both entry points with `HBK_LZ4` for exactly this reason. Arch
-and Nix put their libraries on the default search path, so a plain dependency is enough.
+Homebrew and Nix both wrap the two entry points with `HBK_LZ4` for exactly this reason —
+Nix has no global library directory at all, so the name alone resolves to nothing. Arch
+puts `liblz4.so.1` on the default loader path, so a plain dependency is enough there.
+
+The same shape caused a worse bug: workers are spawned as `sys.executable -m hbkit.runner`,
+and a wrapper script leaves `sys.executable` pointing at an interpreter that cannot import
+hbkit. Fixed in 0.4.3 by passing the parent's `sys.path` down. Any recipe that wraps the
+entry points needs at least 0.4.3.
 
 ## AUR
 
 ```sh
 git clone ssh://aur@aur.archlinux.org/hbkit.git
 cp packaging/aur/PKGBUILD packaging/aur/.SRCINFO hbkit/
-cd hbkit && git add PKGBUILD .SRCINFO && git commit -m "hbkit 0.4.2" && git push
+cd hbkit && git add PKGBUILD .SRCINFO && git commit -m "hbkit 0.4.3" && git push
 ```
 
 `.SRCINFO` must match `PKGBUILD`; regenerate it on Arch with `makepkg --printsrcinfo >

{hbkit-0.4.3 → hbkit-0.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hbkit"
-version = "0.4.3"
+version = "0.4.5"
 description = "Recover files from Synology Hyper Backup (.hbk) archives without Synology software"
 readme = "README.md"
 requires-python = ">=3.10"

{hbkit-0.4.3 → hbkit-0.4.5}/src/hbkit/__init__.py

@@ -1,6 +1,6 @@
 """hbkit - recover files from Synology Hyper Backup (.hbk) archives without Synology software."""
 
-__version__ = "0.4.3"
+__version__ = "0.4.5"
 
 from .archive import (Archive, NeedPassword, UnsupportedArchive,  # noqa: F401
                       find_archive_root, is_archive)

{hbkit-0.4.3 → hbkit-0.4.5}/src/hbkit/archive.py

@@ -118,8 +118,17 @@ class Cat:
     Shards are a fixed SHARD_SIZE except the last, so offsets are computed rather than
     measured. That matters enormously on network mounts: stat-ing every shard cost ~2,600
     round-trips on a 3 TB archive (minutes before reading a byte). We now do one directory
-    listing plus a single stat of the final shard. If the assumption were ever wrong, a
-    short read surfaces as a chunk MD5 failure - loudly - never as silent corruption.
+    listing plus a single stat of the final shard.
+
+    The numbering can have GAPS: a real archive was missing 7.idx from one family and
+    27.idx from another. A shard's logical position therefore comes from its filename,
+    never from its position in the sorted list - compacting the list slides every shard
+    after a gap 8 MiB early, and the wrong bytes still parse as plausible records. That
+    was issue #1: valid chunk lists read as garbage for any file stored past a gap.
+
+    Reading inside a gap returns nothing rather than the neighbouring shard's bytes, so
+    a hole surfaces as a short read and then a loud failure upstream, never as silent
+    corruption.
     """
 
     def __init__(self, d: str):
@@ -136,12 +145,13 @@ class Cat:
                 found[n] = (gen, f)
         if not found:
             raise FileNotFoundError(f"no .idx shards in {d}")
-        self.files = [found[k][1] for k in sorted(found)]
-        n = len(self.files)
+        shard_ids = sorted(found)
+        self.files = [found[k][1] for k in shard_ids]
         last = os.path.getsize(os.path.join(d, self.files[-1]))
-        self.sizes = [SHARD_SIZE] * (n - 1) + [last]
-        self.starts = [i * SHARD_SIZE for i in range(n)]
-        self.total = (n - 1) * SHARD_SIZE + last
+        self.sizes = [SHARD_SIZE] * (len(self.files) - 1) + [last]
+        self.starts = [k * SHARD_SIZE for k in shard_ids]
+        self.total = self.starts[-1] + last
+        self._positions = dict(zip(shard_ids, range(len(shard_ids))))
         self._fh: dict[int, object] = {}
         # Shard 0 carries a 64-byte header that declares the record size, so readers do
         # not have to hardcode per-DSM-version layouts.
@@ -160,15 +170,18 @@ class Cat:
         """Read n bytes at logical offset off, spanning shards as needed."""
         out = b""
         i = off // SHARD_SIZE
-        while n > 0 and i < len(self.files):
-            st = self.starts[i]
-            take = min(n, st + self.sizes[i] - off)
+        while n > 0:
+            pos = self._positions.get(i)
+            if pos is None:
+                break
+            st = self.starts[pos]
+            take = min(n, st + self.sizes[pos] - off)
             if take <= 0:
                 break
-            fh = self._fh.get(i)
+            fh = self._fh.get(pos)
             if fh is None:
-                fh = self._fh[i] = open(os.path.join(self.d, self.files[i]), "rb",
-                                        buffering=INDEX_BUF)
+                fh = self._fh[pos] = open(os.path.join(self.d, self.files[pos]), "rb",
+                                          buffering=INDEX_BUF)
             fh.seek(off - st)
             got = fh.read(take)
             out += got
@@ -210,6 +223,16 @@ class _LazyCats(dict):
     def values(self):
         return [v for v in dict.values(self)]
 
+    @property
+    def known(self) -> list[int]:
+        """Every shard id the archive has, opened or not.
+
+        Iterating the dict yields only what something has already touched, so a
+        caller that just wants to *describe* the archive - `doctor` - has to ask
+        for this instead, or it reports an archive with shards as having none.
+        """
+        return sorted(self._dirs)
+
 
 def is_archive(d: str) -> bool:
     return os.path.isdir(os.path.join(d, "Pool")) and os.path.isdir(os.path.join(d, "Config"))

{hbkit-0.4.3 → hbkit-0.4.5}/src/hbkit/cli.py

@@ -231,7 +231,23 @@ def main() -> int:
 
     if cmd == "doctor":
         from . import doctor
-        r = doctor.diagnose(archive, password=resolve_password(password))
+        sample = None
+        for flag in ("-s", "-n", "--sample"):
+            if flag in a[2:]:
+                i = a.index(flag, 2)
+                try:
+                    sample = int(a[i + 1])
+                except (IndexError, ValueError):
+                    print(f"{flag} requires a positive integer", file=sys.stderr)
+                    return 2
+                if sample < 1:
+                    print(f"{flag} requires a positive integer", file=sys.stderr)
+                    return 2
+                break
+        kw = {"password": resolve_password(password)}
+        if sample is not None:
+            kw["sample"] = sample
+        r = doctor.diagnose(archive, **kw)
         print(doctor.render(r))
         return 0 if (r.ok and not r.blockers) else 1
 

{hbkit-0.4.3 → hbkit-0.4.5}/src/hbkit/doctor.py

@@ -88,7 +88,7 @@ def diagnose(path: str, sample: int = 10, seed: int = 0, password: str | None =
     r.fact("virtual_file record", f"{arc.vf.record_size} B")
     r.fact("chunk_index record", f"{arc.ci.record_size} B "
                                  f"({'v3' if arc.ci.record_size == 29 else 'v1/v2'})")
-    r.fact("file_chunk shards", ", ".join(str(k) for k in sorted(arc.fc)))
+    r.fact("file_chunk shards", ", ".join(str(k) for k in arc.fc.known))
     r.check("virtual_file layout known", arc.vf.record_size == 56, f"{arc.vf.record_size} B")
     r.check("chunk_index layout known", arc.ci.record_size in (16, 29), f"{arc.ci.record_size} B")
 
@@ -202,7 +202,7 @@ def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__)
     ap.add_argument("archive")
     ap.add_argument("-p", "--password", help="for encrypted archives")
-    ap.add_argument("-n", "--sample", type=int, default=10,
+    ap.add_argument("-n", "-s", "--sample", type=int, default=10,
                     help="files to rebuild per share as proof (default 10)")
     a = ap.parse_args()
     r = diagnose(a.archive, a.sample, password=a.password)

{hbkit-0.4.3 → hbkit-0.4.5}/tests/test_hbkit.py

@@ -287,6 +287,18 @@ def test_cat_single_shard_still_works(tmp_path, monkeypatch):
     c.close()
 
 
+def test_cat_preserves_sparse_shard_offsets(tmp_path, monkeypatch):
+    from hbkit import archive as A
+    blob = _make_shards(tmp_path, [128, 10], 128, monkeypatch)
+    (tmp_path / "1.idx.2").rename(tmp_path / "2.idx.2")
+    c = A.Cat(str(tmp_path))
+    assert c.starts == [0, 256]
+    assert c.total == 266
+    assert c.read(128, 1) == b""
+    assert c.read(256, 10) == blob[128:]
+    c.close()
+
+
 # --------------------------------------------------- rclone mount helper (no network)
 
 def test_mount_profiles_pick_the_right_cache_mode(monkeypatch):
@@ -478,3 +490,31 @@ def test_doctor_honours_the_password_environment_variable(monkeypatch, flag, env
     monkeypatch.setattr(sys, "argv", argv)
     assert cli.main() == 0
     assert seen["pw"] == want
+
+
+@pytest.mark.parametrize("flag", ["-s", "-n", "--sample"])
+def test_doctor_forwards_sample_count(monkeypatch, flag):
+    from hbkit import cli, doctor
+
+    seen = {}
+
+    class Result:
+        ok, blockers = True, []
+
+    monkeypatch.setattr(doctor, "diagnose",
+                        lambda a, sample=10, password=None:
+                        (seen.update(sample=sample), Result())[1])
+    monkeypatch.setattr(doctor, "render", lambda r: "")
+    monkeypatch.setattr(sys, "argv", ["hbk", "/some/archive", "doctor", flag, "2"])
+    assert cli.main() == 0
+    assert seen["sample"] == 2
+
+
+def test_lazycats_lists_shards_before_any_are_opened():
+    """`doctor` describes an archive without extracting from it, so nothing has opened a
+    file_chunk shard by the time it prints them. Iterating the dict reported an empty list
+    and made a healthy archive look malformed."""
+    cats = hbk._LazyCats({4: "/nonexistent/file_chunk4.index",
+                          0: "/nonexistent/file_chunk0.index"})
+    assert cats.known == [0, 4]
+    assert len(cats) == 0, "listing shards must not open them"