Skip to content

[2.0.0] Major Release: Universal Snapshot Engine, Btrfs & Snapper Support, Sub-Dataset Boundaries & Strict Type Safety

Choose a tag to compare

View all tags
@NicolasGoeddel NicolasGoeddel released this 29 Aug 10:49
· 17 commits to main since this release
v2.0.0
4a3229d

[2.0.0] - 2026-08-28

Major Release: Universal Snapshot Engine, Btrfs & Snapper Support, Sub-Dataset Boundaries & Strict Type Safety

Version 2.0.0 marks the evolution of ZFS Snapshot Explorer into the Universal Snapshot Explorer (USE). This release introduces a modular, pluggable multi-filesystem engine capable of browsing OpenZFS, Btrfs (including Snapper layouts), and POSIX snapshot directories with full type safety, comprehensive integration testing, and automatic mountpoint boundary discovery.

🚀 Highlights & New Features

  • 🗂️ Universal Multi-Filesystem Engine:

    • Introduced the FilesystemProvider interface and ProviderRegistry allowing modular support for any snapshot-capable filesystem.
    • Added Btrfs & Snapper Support (BtrfsProvider):
      • Automatically discovers active Btrfs subvolumes and .snapshots hierarchies.
      • Parses Snapper XML metadata (info.xml) to extract exact snapshot descriptions, user context, and timestamps.
      • Dynamically resolves snapshot physical paths (.snapshots/<id>/snapshot).
    • Added OpenZFS Provider (ZfsProvider):
      • Native ZFS CLI integration via zfs list -t snapshot for Unix epoch timestamps and dataset autodiscovery.
      • Zero-dependency filesystem fallback mode for unprivileged containers.
    • Added Generic Provider (GenericProvider):
      • Fallback provider supporting NFS, CIFS/SMB, and standard POSIX mounts.

  • 🌐 Smarter Mount & Boundary Detection:

    • Integrated /proc/mounts parsing (MountsManager, MountInfo) to identify nested filesystem boundaries and network mounts.
    • Per-Dataset Snapshot Timelines: Directories that represent independent datasets or mount boundaries (e.g. /root or /data/backups) now render their own dedicated snapshot timeline bars in folder rows and breadcrumbs, rather than incorrectly inheriting the parent dataset's timeline.

  • 📂 Dynamic Relative UID/GID Mapping:

    • Relative user_map and group_map paths (e.g. etc/passwd) are now dynamically resolved from the currently active snapshot and cached per snapshot, accurately reflecting historical users and groups.

🛠️ Architecture & Under the Hood

  • Python 3.14 Future Annotations & Protocol Modernization:
    • Enforced from __future__ import annotations across all 22 source modules.
    • Completely eliminated dynamic getattr(...) calls in favor of typed RootFolderProtocol properties and methods.
  • Strict Type Checking with basedpyright:
    • Entire codebase runs at 0 errors, 0 warnings, 0 notes under strict basedpyright analysis.
  • FastAPI Integration Test Suite:
    • 38 comprehensive unit & integration tests covering routing, error handling, ZFS/Btrfs parsing, mount discovery, permissions, and streaming.
    • Reached 74% total test code coverage.
  • GitHub Actions CI/CD Pipeline:
    • Added .github/workflows/ci.yml running ruff, basedpyright, and coverage checks on Python 3.14.

⚠️ Breaking Changes & Migration Guide

  • Package & CLI Rename:
    • Python package renamed from goeddel.zfs_snapshot_explorer to goeddel.use.
    • Executable command renamed from zfsse to use (or snapshot-explorer).
    • To run locally: uv run use --config-file config.yaml.
  • Docker Image Name:
    • Published to ghcr.io/nicolasgoeddel/universal-snapshot-explorer:latest.
  • Configuration Enhancements:
    • config.yaml now supports btrfs: global auto-discovery blocks alongside zfs:.
    • Manual roots support explicit filesystem_type: zfs | btrfs | generic.
Assets 2
Loading