feat(satellite): on-disk signature cross-check helpers (Phase 10.7)

Pure-function detectors the PhysicalDevice discovery loop will
compose with lsblk's TYPE/FSTYPE filter to publish only truly
free devices:

  HasLVMSignature   — pvs --noheadings -o pv_name | match
  HasZFSSignature   — zpool list -PHv | match (missing tool ⇒ false)
  HasDRBDSignature  — drbdmeta dump-md exit-zero
  HasOtherSignature — wipefs -n non-empty stdout

`IsDeviceFree(ctx, exec, lsblkDevice)` composes everything: the
lsblk row's IsFreeBlockDevice() short-circuits the chain (saves
exec calls on busy hosts with thousands of partitions); the four
signature detectors run in order, first-positive aborts. Each
detector's "tool not installed" path swallows the exec error
(LVM-only host can't have ZFS signatures, FILE-only host can't
have DRBD ones, etc).

Pinned via 6 unit tests covering happy/empty/missing-tool paths
plus the two short-circuit invariants — the "stop after first
positive" + "skip everything when lsblk already disqualified"
optimisations matter on real hardware where these detectors
are the hot path of a 60-second discovery tick.

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Andrei Kvapil <kvapss@gmail.com>

Author: kvaps

pkg/satellite/signatures.go

@@ -0,0 +1,159 @@
+/*
+Copyright 2026 Cozystack contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package satellite
+
+import (
+	"context"
+	"strings"
+
+	"github.com/cockroachdb/errors"
+
+	"github.com/cozystack/blockstor/pkg/storage"
+)
+
+// HasLVMSignature reports whether the named device is already a
+// member of an LVM physical volume. The discovery loop runs this
+// (alongside HasZFSSignature, HasDRBDSignature, HasOtherSignature)
+// before publishing a device as a `PhysicalDevice` CRD —
+// `lsblk` alone misses already-attached LVM PVs that haven't been
+// fully formatted with a kernel-recognised signature.
+//
+// Method: `pvs --noheadings -o pv_name` lists every PV the host
+// knows about. We string-match the device path. Empty stdout
+// means no PVs at all on this host (fresh install) — return
+// false. Phase 10.7.
+func HasLVMSignature(ctx context.Context, exec storage.Exec, devicePath string) (bool, error) {
+	out, err := exec.Run(ctx, "pvs", "--noheadings", "-o", "pv_name")
+	if err != nil {
+		return false, errors.Wrap(err, "pvs")
+	}
+
+	for line := range strings.SplitSeq(string(out), "\n") {
+		if strings.TrimSpace(line) == devicePath {
+			return true, nil
+		}
+	}
+
+	return false, nil
+}
+
+// HasZFSSignature reports whether the named device is part of any
+// imported ZFS pool. `zpool list -PHv` walks every pool's vdev
+// tree; we string-match the device path against any line.
+//
+// `-P` forces full device paths (so we can compare against
+// /dev/disk/by-id symlinks); `-H` strips the header; `-v`
+// expands vdevs. Phase 10.7.
+func HasZFSSignature(ctx context.Context, exec storage.Exec, devicePath string) (bool, error) {
+	out, err := exec.Run(ctx, "zpool", "list", "-PHv")
+	if err != nil {
+		// `zpool` may not be installed (FILE / LVM-only host); a
+		// missing binary surfaces as exec error, which we treat
+		// as "no ZFS in play, so no signature". The caller is
+		// responsible for distinguishing "missing tool" from
+		// "real failure" via the error type if needed.
+		return false, nil
+	}
+
+	for line := range strings.SplitSeq(string(out), "\n") {
+		// zpool list -v rows are tab/space separated; the first
+		// column is either the pool name (no leading whitespace)
+		// or a vdev / device (leading whitespace). We just look
+		// for the substring; false-positives on pool names that
+		// happen to contain `/dev/...` are pathological.
+		if strings.Contains(line, devicePath) {
+			return true, nil
+		}
+	}
+
+	return false, nil
+}
+
+// HasDRBDSignature reports whether the named device carries a
+// DRBD-9 metadata block. `drbdmeta dump-md` reads the metadata
+// block — exit-zero means it parsed something, exit-non-zero
+// means no recognisable metadata. We don't care about the parsed
+// content here, only the success/failure signal.
+//
+// We pass `0 v09 <device> internal` (minor 0, version 9, internal
+// metadata) — drbdmeta accepts a placeholder minor since we're
+// only reading. Phase 10.7.
+func HasDRBDSignature(ctx context.Context, exec storage.Exec, devicePath string) (bool, error) {
+	_, err := exec.Run(ctx, "drbdmeta", "0", "v09", devicePath, "internal", "dump-md")
+	if err != nil {
+		// Any failure (no metadata / drbdmeta missing / read error)
+		// → treat as no signature. The caller's `wipefs -n` pass
+		// catches anything else.
+		return false, nil //nolint:nilerr // any drbdmeta failure ⇒ no DRBD signature
+	}
+
+	return true, nil
+}
+
+// HasOtherSignature is the catch-all that uses `wipefs -n` to
+// detect filesystem / RAID / partition-table signatures lsblk's
+// FSTYPE column may have missed. `-n` is dry-run: lists matches
+// without modifying the device. Non-empty stdout = at least one
+// signature found.
+func HasOtherSignature(ctx context.Context, exec storage.Exec, devicePath string) (bool, error) {
+	out, err := exec.Run(ctx, "wipefs", "-n", devicePath)
+	if err != nil {
+		return false, errors.Wrap(err, "wipefs")
+	}
+
+	return strings.TrimSpace(string(out)) != "", nil
+}
+
+// IsDeviceFree composes the four cross-checks: a device is free
+// iff lsblk-derived `IsFreeBlockDevice` returns true AND none of
+// the four signature detectors fired. Returns the first error
+// encountered; pre-empts subsequent checks (so a ZFS-host that
+// has `zpool` installed but pvs missing fails cleanly on the
+// LVM check rather than silently treating "exec error" as
+// "free").
+//
+// The lsblk row stays the single source of truth for the
+// device path — we feed `LsblkDevice.KName` (e.g. `/dev/sda`)
+// into the signature checks since that's what pvs/zpool/drbdmeta
+// all expect.
+func IsDeviceFree(ctx context.Context, exec storage.Exec, dev *LsblkDevice) (bool, error) {
+	if !dev.IsFreeBlockDevice() {
+		return false, nil
+	}
+
+	devicePath := "/dev/" + dev.KName
+
+	checks := []func(context.Context, storage.Exec, string) (bool, error){
+		HasLVMSignature,
+		HasZFSSignature,
+		HasDRBDSignature,
+		HasOtherSignature,
+	}
+
+	for _, check := range checks {
+		has, err := check(ctx, exec, devicePath)
+		if err != nil {
+			return false, err
+		}
+
+		if has {
+			return false, nil
+		}
+	}
+
+	return true, nil
+}

pkg/satellite/signatures_test.go

@@ -0,0 +1,172 @@
+/*
+Copyright 2026 Cozystack contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package satellite_test
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/cozystack/blockstor/pkg/satellite"
+	"github.com/cozystack/blockstor/pkg/storage"
+)
+
+// errZpoolNotFound stands in for the exec.Command-not-found error
+// FakeExec surfaces when the host doesn't have ZFS installed. The
+// LVM-only-host path is the one we most care about pinning.
+var errZpoolNotFound = errors.New("zpool: command not found")
+
+// TestHasLVMSignaturePvsMatch pins the LVM signature detection: a
+// device path appearing in `pvs --noheadings -o pv_name` output
+// surfaces as has=true. Each line is trimmed before comparison so
+// pvs's typical leading-spaces formatting doesn't break the match.
+func TestHasLVMSignaturePvsMatch(t *testing.T) {
+	t.Parallel()
+
+	fx := storage.NewFakeExec()
+	fx.Expect("pvs --noheadings -o pv_name",
+		storage.FakeResponse{Stdout: []byte("  /dev/sda\n  /dev/nvme0n1\n")})
+
+	has, err := satellite.HasLVMSignature(t.Context(), fx, "/dev/sda")
+	if err != nil {
+		t.Fatalf("HasLVMSignature: %v", err)
+	}
+
+	if !has {
+		t.Errorf("got has=false, want true (sda is in pvs output)")
+	}
+}
+
+// TestHasLVMSignatureNoMatch pins the empty-output / missing-device
+// case: `pvs` reports no PVs (empty stdout) → has=false.
+func TestHasLVMSignatureNoMatch(t *testing.T) {
+	t.Parallel()
+
+	fx := storage.NewFakeExec()
+	fx.Expect("pvs --noheadings -o pv_name",
+		storage.FakeResponse{Stdout: []byte("")})
+
+	has, err := satellite.HasLVMSignature(t.Context(), fx, "/dev/sda")
+	if err != nil {
+		t.Fatalf("HasLVMSignature: %v", err)
+	}
+
+	if has {
+		t.Errorf("got has=true on empty pvs output, want false")
+	}
+}
+
+// TestHasZFSSignatureMissingTool pins the LVM-only-host path:
+// `zpool` not installed surfaces as exec error from FakeExec. The
+// detector swallows it (has=false) — the host can't have ZFS
+// signatures if there's no ZFS at all.
+func TestHasZFSSignatureMissingTool(t *testing.T) {
+	t.Parallel()
+
+	fx := storage.NewFakeExec()
+	fx.Expect("zpool list -PHv",
+		storage.FakeResponse{Err: errZpoolNotFound})
+
+	has, err := satellite.HasZFSSignature(t.Context(), fx, "/dev/sda")
+	if err != nil {
+		t.Errorf("HasZFSSignature: missing tool must NOT propagate error, got %v", err)
+	}
+
+	if has {
+		t.Errorf("got has=true on missing zpool, want false")
+	}
+}
+
+// TestHasOtherSignatureWipefsNonEmpty: wipefs -n with non-empty
+// output (any signature found) → has=true. This is the catch-all
+// for filesystem / RAID / partition-table signatures lsblk's FSTYPE
+// column may have missed.
+func TestHasOtherSignatureWipefsNonEmpty(t *testing.T) {
+	t.Parallel()
+
+	fx := storage.NewFakeExec()
+	fx.Expect("wipefs -n /dev/sda",
+		storage.FakeResponse{Stdout: []byte("/dev/sda: 8 bytes were erased at offset 0x00000218 (md_raid_member): fc 4e 2b a9\n")})
+
+	has, err := satellite.HasOtherSignature(t.Context(), fx, "/dev/sda")
+	if err != nil {
+		t.Fatalf("HasOtherSignature: %v", err)
+	}
+
+	if !has {
+		t.Errorf("got has=false on non-empty wipefs output, want true")
+	}
+}
+
+// TestIsDeviceFreeAllChecksPassButLVM pins the short-circuit
+// behaviour of IsDeviceFree: as soon as one of the four signature
+// detectors fires, the rest are skipped. This is load-bearing —
+// running drbdmeta on every device on a busy host is expensive.
+func TestIsDeviceFreeAllChecksPassButLVM(t *testing.T) {
+	t.Parallel()
+
+	fx := storage.NewFakeExec()
+	fx.Expect("pvs --noheadings -o pv_name",
+		storage.FakeResponse{Stdout: []byte("/dev/sda\n")})
+
+	dev := &satellite.LsblkDevice{
+		Name:  "sda",
+		KName: "sda",
+		Type:  "disk",
+		// FSType, Mountpoint empty → passes IsFreeBlockDevice
+	}
+
+	free, err := satellite.IsDeviceFree(t.Context(), fx, dev)
+	if err != nil {
+		t.Fatalf("IsDeviceFree: %v", err)
+	}
+
+	if free {
+		t.Errorf("got free=true, want false (sda has LVM signature)")
+	}
+
+	// Pin the short-circuit: zpool / drbdmeta / wipefs MUST NOT
+	// have been called once LVM said "no".
+	for _, line := range fx.CommandLines() {
+		if line != "pvs --noheadings -o pv_name" {
+			t.Errorf("unexpected exec call after LVM positive: %q", line)
+		}
+	}
+}
+
+// TestIsDeviceFreeShortCircuitsOnLsblkRejection: when the lsblk
+// row already disqualifies the device (TYPE=part), no signature
+// detectors run at all — saves time on busy hosts with thousands
+// of partitions.
+func TestIsDeviceFreeShortCircuitsOnLsblkRejection(t *testing.T) {
+	t.Parallel()
+
+	fx := storage.NewFakeExec()
+	dev := &satellite.LsblkDevice{Name: "sda1", KName: "sda1", Type: "part"}
+
+	free, err := satellite.IsDeviceFree(t.Context(), fx, dev)
+	if err != nil {
+		t.Fatalf("IsDeviceFree: %v", err)
+	}
+
+	if free {
+		t.Errorf("got free=true on TYPE=part, want false")
+	}
+
+	if len(fx.CommandLines()) != 0 {
+		t.Errorf("expected no exec calls on lsblk-rejected device; got %v", fx.CommandLines())
+	}
+}