From 918564bf4f4dffc1033740aee9ba51881c81dbff Mon Sep 17 00:00:00 2001 From: Andrea Mazzoleni Date: Tue, 25 Aug 2026 22:27:53 +0200 Subject: [PATCH] Update TODO --- TODO | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/TODO b/TODO index 5c0e630f..7b704634 100644 --- a/TODO +++ b/TODO @@ -12,6 +12,78 @@ All done ? ============= * Use statx() instead of lstat() when scanning directories. + Besides providing the normal stat information, statx() exposes metadata that + is useful to correctly identify filesystem, mount, and subvolume boundaries + that cannot be detected reliably with st_dev alone. + + The scanner should identify the data root using three values: + + ``` + st_dev + stx_mnt_id + stx_subvol + ``` + + and avoid descending into a directory whenever any of these identifiers is + different from the corresponding identifier of the data root. + + st_dev remains the primary and always available check. It detects different + filesystems and also already detects nested Btrfs subvolumes, because Btrfs + reports a different st_dev for different subvolumes. + + Use STATX_MNT_ID/stx_mnt_id to additionally detect different mount instances, + including bind mounts of the same filesystem. Such mounts can have the same + st_dev and therefore cannot be detected by the current st_dev comparison + alone. + + Use STATX_SUBVOL/stx_subvol to detect nested Bcachefs subvolumes. Bcachefs + subvolumes can share the same st_dev and mount ID while having different + subvolume IDs. This additional subvolume check is not required for Btrfs, + where st_dev already distinguishes nested subvolumes. + + Do not make STATX_SUBVOL support depend only on the kernel headers available + at build time. A SnapRAID binary built on an older system should still be + able to use stx_subvol when later executed on a newer kernel/filesystem that + supports it. STATX_SUBVOL was added in Linux 6.10 by consuming previously + reserved space in struct statx, so its ABI can be handled compatibly even + when compiling against older headers. + + Provide compatibility definitions for missing STATX_SUBVOL/stx_subvol ABI + declarations where necessary, ideally isolated in the portability layer + instead of exposing header-version conditionals to the scanner. If support + for build environments predating the libc statx() wrapper is required, + consider implementing the portability wrapper using the raw statx syscall so + that availability is determined by the runtime kernel rather than by the + libc version used to build SnapRAID. + + Internally, missing optional identifiers may be represented as 0: + + ``` + mnt_id = 0 if STATX_MNT_ID is unavailable + subvol_id = 0 if STATX_SUBVOL is unavailable + ``` + + The comparison can then remain simple: + + ``` + if (st_dev != root_st_dev || + mnt_id != root_mnt_id || + subvol_id != root_subvol_id) + /* do not descend */ + ``` + + This works because st_dev is always compared as well, while the optional + identifiers are expected to be available consistently for objects on the + same filesystem during a scan. On systems where an optional statx field is + unavailable, both the root and its descendants will normally receive 0 for + that identifier, naturally falling back to the existing st_dev-only + behavior. + + Note that 0 is an internal SnapRAID value meaning "identifier unavailable"; + it must not be interpreted as a kernel guarantee that mount ID 0 or + subvolume ID 0 can never be valid. The design relies only on unavailable + optional information comparing equal and therefore not introducing an + additional boundary check. * Add a new 'restore' command, similar to 'fix', that recovers a whole disk using the same multithreaded approach as sync/scrub.