lualoader: allow the local module to filter out the BE list

This allows something like the following local.lua to install a filter
to implement its own notion of hidden BEs using a naming convention of
a leading dot to hide them:

-- file: /boot/lua/local.lua
local core = require("core")

local function be_hide(be)
    if core.isSingleUserBoot() then
        -- All BEs are accepted for single-user
        return true
    end

    local name = be:match("/([^/]+)$")
    if not name then
        -- Accept malformed BEs, for whatever reason
        return true
    end

    return name:match("^%.") == nil
end

if core.bootenvFilter then
    -- Just in case we need to be compatible with older versions of
    -- core.lua without the filtering functionality.
    core.bootenvFilter(be_hide)
end
-- EOF

Requested by:	Marek Zarychta
Reviewed by:	imp
Differential Revision:	https://reviews.freebsd.org/D55359

stand/lua/core.lua

@@ -305,6 +305,15 @@ function core.bootenvDefault()
 	return loader.getenv("zfs_be_active")
 end
 
+function core.bootenvFilter(func)
+	local oldf = core.bootenv_filter
+
+	-- Filter contract: returns true if the BE should be kept, false if it
+	-- should be hidden.
+	core.bootenv_filter = func
+	return oldf
+end
+
 function core.bootenvList()
 	local bootenv_count = tonumber(loader.getenv(bootenv_list .. "_count"))
 	local bootenvs = {}
@@ -332,11 +341,18 @@ function core.bootenvList()
 	for curenv_idx = 0, bootenv_count - 1 do
 		curenv = loader.getenv(bootenv_list .. "[" .. curenv_idx .. "]")
 		if curenv ~= nil and unique[curenv] == nil then
-			envcount = envcount + 1
-			bootenvs[envcount] = curenv
 			unique[curenv] = true
+
+			-- If we have a filter installed (by a local module), we
+			-- give it a chance to veto the BE.
+			if not core.bootenv_filter or
+			    core.bootenv_filter(curenv) then
+				envcount = envcount + 1
+				bootenvs[envcount] = curenv
+			end
 		end
 	end
+
 	return bootenvs
 end
 

stand/lua/core.lua.8

@@ -24,7 +24,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd March 29, 2025
+.Dd April 8, 2026
 .Dt CORE.LUA 8
 .Os
 .Sh NAME
@@ -164,6 +164,17 @@ is set in
 kernels will be autodetected from the current system.
 .It Fn core.bootenvDefault
 Returns the default boot environment, nil if unset.
+.It Fn core.bootenvFilter func
+Installs a filter
+.Fa func
+into
+.Fn core.bootenvList .
+If the
+.Fa func
+returns true, then the boot environment is retained in the list.
+Otherwise, the boot environment is hidden.
+The old filter, if any, is returned to allow the caller to compose a filter on
+top of another filter.
 .It Fn core.bootenvList
 Returns a table of boot environments, or an empty table.
 These will be picked up using the