Implemented explicit source boot stanza exclusion

Author: Venom1991

README.md

@@ -139,7 +139,7 @@ I'm assuming here that the next available subvolume ID was 503 (an increment of
 With this setup the newly created snapshot ended up being nested under the root subvolume but you can of course make your own adjustments as you see fit. This tool will only create the destination directory in case it doesn't exist. It won't do anything other than that.  
 I've personally created another subvolume named @rw-snapshots directly under the default filesystem subvolume (ID 5) and mounted it at /root/.refind-btrfs. In my case the logical path of rwsnap_2020-12-14_05-00-00_ID502 would be /@rw-snapshots/rwsnap_2020-12-14_05-00-00_ID502.
 
-A generated manual boot stanza's file name is formatted like "{volume}_{loader}.conf" and converted to all lowercase letters which would result in, for this example, a file named "arch_vmlinuz-linux.conf". This file is then saved in a subdirectory (relative to rEFInd's root directory) named "btrfs-snapshot-stanzas" and finally included in the main config file by appending an "include" directive which would, again for this example, look like this: "include btrfs-snapshot-stanzas/arch_vmlinuz-linux.conf". This last step is performed only once, during an initial run. Afterwards, it is detected as already being included in the main config file.
+A generated manual boot stanza's filename is formatted like "{volume}_{loader}.conf" and converted to all lowercase letters which would result in, for this example, a file named "arch_vmlinuz-linux.conf". This file is then saved in a subdirectory (relative to rEFInd's root directory) named "btrfs-snapshot-stanzas" and finally included in the main config file by appending an "include" directive which would, again for this example, look like this: "include btrfs-snapshot-stanzas/arch_vmlinuz-linux.conf". This last step is performed only once, during an initial run. Afterwards, it is detected as already being included in the main config file.
 
 You are free to rearrange the appended include directives however you want, this tool does not care about where exactly they appear in the main config file. This is particularly useful in case you've defined multiple boot stanzas (each one pointing to a different kernel image, for example) and wish to alter the order of the boot menu entries.
 

src/refind_btrfs/boot/boot_stanza.py

@@ -23,11 +23,12 @@
 
 from __future__ import annotations
 
+import inspect
 import re
 from collections import defaultdict
-from functools import cached_property
+from functools import cached_property, singledispatchmethod
 from itertools import chain
-from typing import DefaultDict, Iterable, Iterator, Optional, Set
+from typing import Any, DefaultDict, Iterable, Iterator, Optional, Set
 
 from more_itertools import always_iterable, last
 
@@ -207,22 +208,14 @@ def with_sub_menus(self, sub_menus: Iterable[SubMenu]) -> BootStanza:
 
         return self
 
-    def is_matched_with(self, block_device: BlockDevice) -> bool:
-        if self.can_be_used_for_bootable_snapshot():
-            boot_options = self.boot_options
-
-            if boot_options.is_matched_with(block_device):
-                return True
-            else:
-                sub_menus = self.sub_menus
-
-                if has_items(sub_menus):
-                    return any(
-                        sub_menu.is_matched_with(block_device)
-                        for sub_menu in none_throws(sub_menus)
-                    )
+    @singledispatchmethod
+    def is_matched_with(self, argument: Any) -> bool:
+        frame = none_throws(inspect.currentframe())
 
-        return False
+        raise NotImplementedError(
+            f"Cannot call the '{inspect.getframeinfo(frame).function}' method "
+            f"for parameter of type '{type(argument).__name__}'!"
+        )
 
     def has_unmatched_boot_files(self) -> bool:
         boot_files_check_result = self.boot_files_check_result
@@ -276,6 +269,28 @@ def validate_icon_path(
                     "icon generation!"
                 )
 
+    @is_matched_with.register(BlockDevice)
+    def _is_matched_with_block_device(self, block_device: BlockDevice) -> bool:
+        if self.can_be_used_for_bootable_snapshot():
+            boot_options = self.boot_options
+
+            if boot_options.is_matched_with(block_device):
+                return True
+            else:
+                sub_menus = self.sub_menus
+
+                if has_items(sub_menus):
+                    return any(
+                        sub_menu.is_matched_with(block_device)
+                        for sub_menu in none_throws(sub_menus)
+                    )
+
+        return False
+
+    @is_matched_with.register(str)
+    def _is_matched_with_loader_filename(self, loader_filename: str) -> bool:
+        return self._loader_filename == loader_filename
+
     def _get_all_boot_file_paths(
         self,
     ) -> Iterator[tuple[BootFilePathSource, str]]:
@@ -369,17 +384,13 @@ def sub_menus(self) -> Optional[list[SubMenu]]:
         return self._sub_menus
 
     @cached_property
-    def file_name(self) -> str:
+    def filename(self) -> str:
         if self.can_be_used_for_bootable_snapshot():
             normalized_volume = self.normalized_volume
-            dir_separator_pattern = re.compile(constants.DIR_SEPARATOR_PATTERN)
-            split_loader_path = dir_separator_pattern.split(
-                none_throws(self.loader_path)
-            )
-            loader = last(split_loader_path)
+            loader_filename = self._loader_filename
             extension = constants.CONFIG_FILE_EXTENSION
 
-            return f"{normalized_volume}_{loader}{extension}".lower()
+            return f"{normalized_volume}_{loader_filename}{extension}".lower()
 
         return constants.EMPTY_STR
 
@@ -395,3 +406,17 @@ def all_boot_file_paths(self) -> DefaultDict[BootFilePathSource, Set[str]]:
             result[key].add(value)
 
         return result
+
+    @cached_property
+    def _loader_filename(self) -> str:
+        loader_path = self.loader_path
+
+        if not is_none_or_whitespace(loader_path):
+            dir_separator_pattern = re.compile(constants.DIR_SEPARATOR_PATTERN)
+            split_loader_path = dir_separator_pattern.split(
+                none_throws(self.loader_path)
+            )
+
+            return last(split_loader_path)
+
+        return constants.EMPTY_STR

src/refind_btrfs/boot/refind_config.py

@@ -139,14 +139,14 @@ def generate_new_from(
                 migrated_boot_stanza = migration.migrate(
                     file_path, boot_stanza_generation, icon_command
                 )
-                boot_stanza_file_name = migrated_boot_stanza.file_name
+                boot_stanza_filename = migrated_boot_stanza.filename
 
-                if not is_none_or_whitespace(boot_stanza_file_name):
+                if not is_none_or_whitespace(boot_stanza_filename):
                     destination_directory = (
                         parent_directory / constants.SNAPSHOT_STANZAS_DIR_NAME
                     )
                     boot_stanza_config_file_path = (
-                        destination_directory / boot_stanza_file_name
+                        destination_directory / boot_stanza_filename
                     )
                     boot_stanza_config = RefindConfig(
                         boot_stanza_config_file_path.resolve()

src/refind_btrfs/common/constants.py

@@ -87,7 +87,7 @@
 )
 
 CONFIG_FILE_EXTENSION = ".conf"
-CONFIG_FILE_NAME = PACKAGE_NAME + CONFIG_FILE_EXTENSION
+CONFIG_FILENAME = PACKAGE_NAME + CONFIG_FILE_EXTENSION
 SNAPSHOT_STANZAS_DIR_NAME = "btrfs-snapshot-stanzas"
 ICONS_DIR = "icons"
 
@@ -98,7 +98,7 @@
 LIB_DIR = Path("lib")
 
 FSTAB_FILE = ETC_DIR / "fstab"
-PACKAGE_CONFIG_FILE = ROOT_DIR / ETC_DIR / CONFIG_FILE_NAME
+PACKAGE_CONFIG_FILE = ROOT_DIR / ETC_DIR / CONFIG_FILENAME
 PACKAGE_LIB_DIR = ROOT_DIR / VAR_DIR / LIB_DIR / PACKAGE_NAME
 BTRFS_LOGOS_DIR = PACKAGE_LIB_DIR / ICONS_DIR / "btrfs_logo"
 DB_FILE = PACKAGE_LIB_DIR / "local_db"

src/refind_btrfs/common/enums.py

@@ -133,6 +133,7 @@ class BootStanzaGenerationConfigKey(AutoNameToLower):
     REFIND_CONFIG = auto()
     INCLUDE_PATHS = auto()
     INCLUDE_SUB_MENUS = auto()
+    SOURCE_EXCLUSION = auto()
     ICON = auto()
 
 

src/refind_btrfs/common/package_config.py

@@ -83,6 +83,7 @@ class BootStanzaGeneration(NamedTuple):
     refind_config: str
     include_paths: bool
     include_sub_menus: bool
+    source_exclusion: Set[str]
     icon: Icon
 
     def with_include_paths(
@@ -94,7 +95,11 @@ def with_include_paths(
             include_paths = boot_device is None
 
         return BootStanzaGeneration(
-            self.refind_config, include_paths, self.include_sub_menus, self.icon
+            self.refind_config,
+            include_paths,
+            self.include_sub_menus,
+            self.source_exclusion,
+            self.icon,
         )
 
 

src/refind_btrfs/data/refind-btrfs.conf-sample

@@ -128,11 +128,24 @@ cleanup_exclusion = []
 ## "selection_count" value (greater than 10, for example) or, worse yet, by
 ## setting it to "inf" can potentially result in an overcrowded "Boot Options"
 ## menu.
+#
+## source_exclusion = <array<string>>
+## Array comprised of loader filenames ("loader") with which the matched source
+## boot stanzas can be arbitrarily excluded from processing, i.e., these boot
+## stanzas will not be taken into account during the generation phase.
+## For example, it can be defined as: ["vmlinuz-linux", "vmlinuz-linux-lts"].
+## WARNING: This array must not contain all of the matched source boot stanza's
+## loader filenames. If it does, an error is issued and a premature exit is
+## performed.
+## Also, a manual cleanup of the generated boot stanza (or stanzas) and its
+## inclusion within the rEFInd's main configuration file is required in case
+## the array's members were defined after the fact.
 
 [boot-stanza-generation]
 refind_config = "refind.conf"
 include_paths = true
 include_sub_menus = false
+source_exclusion = []
 
 # [boot-stanza-generation.icon]
 ## Subobject used to configure the process of defining the generated boot

src/refind_btrfs/device/partition.py

@@ -113,15 +113,15 @@ def is_boot(self) -> bool:
 
         return False
 
-    def search_paths_for(self, file_name: str) -> Optional[list[Path]]:
-        if is_none_or_whitespace(file_name):
-            raise ValueError("The 'file_name' parameter must be initialized!")
+    def search_paths_for(self, filename: str) -> Optional[list[Path]]:
+        if is_none_or_whitespace(filename):
+            raise ValueError("The 'filename' parameter must be initialized!")
 
         filesystem = none_throws(self.filesystem)
 
         if filesystem.is_mounted():
             search_directory = Path(filesystem.mount_point)
-            all_matches = find_all_matched_files_in(search_directory, file_name)
+            all_matches = find_all_matched_files_in(search_directory, filename)
 
             return list(all_matches)
 

src/refind_btrfs/state_management/conditions.py

@@ -232,9 +232,28 @@ def check_boot_stanzas_with_snapshots(self) -> bool:
         logger = self._logger
         model = self._model
         boot_stanzas_with_snapshots = model.boot_stanzas_with_snapshots
+        excluded_boot_stanzas_count = len(
+            list(item for item in boot_stanzas_with_snapshots if item.is_excluded)
+        )
+
+        if len(boot_stanzas_with_snapshots) == excluded_boot_stanzas_count:
+            logger.error(
+                "All of the matched boot stanzas are "
+                "explicitly excluded from processing!"
+            )
+
+            return False
 
         for item in boot_stanzas_with_snapshots:
-            if item.has_unmatched_snapshots():
+            boot_stanza = item.boot_stanza
+            normalized_name = boot_stanza.normalized_name
+
+            if item.is_excluded:
+                logger.info(
+                    f"Skipping the '{normalized_name}' boot stanza "
+                    "because it is explicitly excluded from processing."
+                )
+            elif item.has_unmatched_snapshots():
                 unmatched_snapshots = item.unmatched_snapshots
 
                 for snapshot in unmatched_snapshots:
@@ -243,14 +262,11 @@ def check_boot_stanzas_with_snapshots(self) -> bool:
                     except SubvolumeError as e:
                         logger.warning(e.formatted_message)
 
-            if not item.has_matched_snapshots():
-                boot_stanza = item.boot_stanza
-                normalized_name = boot_stanza.normalized_name
-
-                logger.warning(
-                    "None of the prepared snapshots are matched "
-                    f"with the '{normalized_name}' boot stanza!"
-                )
+                if not item.has_matched_snapshots():
+                    logger.warning(
+                        "None of the prepared snapshots are matched "
+                        f"with the '{normalized_name}' boot stanza!"
+                    )
 
         usable_boot_stanzas_with_snapshots = model.usable_boot_stanzas_with_snapshots
 

src/refind_btrfs/state_management/model.py

@@ -72,6 +72,7 @@ def has_changes(self) -> bool:
 
 class BootStanzaWithSnapshots(NamedTuple):
     boot_stanza: BootStanza
+    is_excluded: bool
     matched_snapshots: list[Subvolume]
     unmatched_snapshots: list[Subvolume]
 
@@ -81,6 +82,9 @@ def has_matched_snapshots(self) -> bool:
     def has_unmatched_snapshots(self) -> bool:
         return has_items(self.unmatched_snapshots)
 
+    def is_usable(self) -> bool:
+        return not self.is_excluded and self.has_matched_snapshots()
+
     def replace_matched_snapshot(
         self, current_snapshot: Subvolume, replacement_snapshot: Subvolume
     ) -> None:
@@ -229,6 +233,7 @@ def initialize_prepared_snapshots(self) -> None:
     def combine_boot_stanzas_with_snapshots(self) -> None:
         usable_boot_stanzas = self.usable_boot_stanzas
         actual_bootable_snapshots = self.actual_bootable_snapshots
+        boot_stanza_generation = self.package_config.boot_stanza_generation
         include_paths = self._should_include_paths_during_generation()
         boot_stanza_preparation_results: list[BootStanzaWithSnapshots] = []
 
@@ -241,6 +246,10 @@ def combine_boot_stanzas_with_snapshots(self) -> None:
                     snapshot.with_boot_files_check_result(boot_stanza)
                     for snapshot in actual_bootable_snapshots
                 )
+                is_excluded = any(
+                    boot_stanza.is_matched_with(loader_filename)
+                    for loader_filename in boot_stanza_generation.source_exclusion
+                )
 
                 for snapshot in checked_bootable_snapshots:
                     append_func = (
@@ -255,7 +264,7 @@ def combine_boot_stanzas_with_snapshots(self) -> None:
 
             boot_stanza_preparation_results.append(
                 BootStanzaWithSnapshots(
-                    boot_stanza, matched_snapshots, unmatched_snapshots
+                    boot_stanza, is_excluded, matched_snapshots, unmatched_snapshots
                 )
             )
 
@@ -469,5 +478,5 @@ def usable_boot_stanzas_with_snapshots(self) -> dict[BootStanza, list[Subvolume]
         return {
             item.boot_stanza: item.matched_snapshots
             for item in boot_stanzas_with_snapshots
-            if item.has_matched_snapshots()
+            if item.is_usable()
         }

src/refind_btrfs/utility/file_package_config_provider.py

@@ -91,6 +91,7 @@ class FilePackageConfigProvider(BasePackageConfigProvider):
             "refind.conf",
             True,
             False,
+            set(),
             Icon(
                 BootStanzaIconGenerationMode.DEFAULT,
                 Path("btrfs-snapshot-stanzas/icons/sample_icon.png"),
@@ -435,6 +436,23 @@ def _map_to_boot_stanza_generation(
             bool,
             default_boot_stanza_generation,
         )
+        source_exclusion_key = BootStanzaGenerationConfigKey.SOURCE_EXCLUSION.value
+        source_exclusion = cast(
+            list,
+            FilePackageConfigProvider._get_config_value(
+                container,
+                source_exclusion_key,
+                list,
+                default_boot_stanza_generation,
+            ),
+        )
+
+        if has_items(source_exclusion):
+            for item in source_exclusion:
+                if not isinstance(item, str):
+                    raise PackageConfigError(
+                        f"Every member of the '{source_exclusion_key}' array must be a string!"
+                    )
 
         icon_key = BootStanzaGenerationConfigKey.ICON.value
 
@@ -447,7 +465,11 @@ def _map_to_boot_stanza_generation(
             icon = default_boot_stanza_generation.icon
 
         return BootStanzaGeneration(
-            refind_config, include_paths, include_sub_menus, icon
+            refind_config,
+            include_paths,
+            include_sub_menus,
+            set(cast(str, loader_filename) for loader_filename in source_exclusion),
+            icon,
         )
 
     @staticmethod

src/refind_btrfs/utility/helpers.py

@@ -128,16 +128,16 @@ def item_count_suffix(value: Sized) -> str:
     return constants.EMPTY_STR if is_singleton(value) else "s"
 
 
-def find_all_matched_files_in(root_directory: Path, file_name: str) -> Iterator[Path]:
+def find_all_matched_files_in(root_directory: Path, filename: str) -> Iterator[Path]:
     if root_directory.exists() and root_directory.is_dir():
         children = root_directory.iterdir()
 
         for child in children:
             if child.is_file():
-                if child.name == file_name:
+                if child.name == filename:
                     yield child
             elif child.is_dir():
-                yield from find_all_matched_files_in(child, file_name)
+                yield from find_all_matched_files_in(child, filename)
 
 
 def find_all_directories_in(