Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Attach subject report alerts with shared disk hardware ownership

pulse-triage[bot]92eef9809bd6
diff --git a/.github/workflows/repo-boundary-audit.yml b/.github/workflows/repo-boundary-audit.yml
index 99e8a6f5a7..02dce6acf1 100644
--- a/.github/workflows/repo-boundary-audit.yml
+++ b/.github/workflows/repo-boundary-audit.yml
@@ -22,6 +22,9 @@ jobs:
sudo apt-get update
sudo apt-get install --yes --no-install-recommends ripgrep
+ - name: Verify shared reporting boundary exemption
+ run: python3 scripts/repo-boundary-regression.py
+
- name: Run Boundary Audit (report mode)
run: |
./scripts/audit-private-boundary.sh | tee repo-boundary-audit.txt
diff --git a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
index dca25cea2b..4e4f0dc81a 100644
--- a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
+++ b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
@@ -2832,6 +2832,13 @@ agent inventory, registration state, or command-channel readiness.
recovered. That is report presentation only: the report never decides
agent linkage, ownership of a metric, or agent freshness, and it adds no
lifecycle state.
+ Reports on an `agent` resource (`internal/api/reporting_subject_alerts.go`)
+ read the agent's host ID from the unified resource's agent payload, only
+ when the agent source is present, to attach that agent's `agent:<host>`
+ alerts and component children beside the linked node's alerts. The
+ report reads linkage the registry already resolved; it never links,
+ unlinks, identifies or authorizes an agent, and it adds no lifecycle
+ state.
The same isolation rule applies to Patrol investigation-record propagation
through shared AI intelligence handlers and `internal/api/router.go`:
lifecycle surfaces may observe the resulting resource context, but they must
diff --git a/docs/release-control/v6/internal/subsystems/api-contracts.md b/docs/release-control/v6/internal/subsystems/api-contracts.md
index 85f3a75f50..514c91c991 100644
--- a/docs/release-control/v6/internal/subsystems/api-contracts.md
+++ b/docs/release-control/v6/internal/subsystems/api-contracts.md
@@ -9795,14 +9795,64 @@ aggregate, health card, table and resource blocks, and the fleet heuristic
recommends checking the agent it moved to. "Triggered and resolved" counts
recoveries only, and the report narrator's payload marks a covered handover
with `successor_alert_listed` so the model describes the condition once.
-Reports requested as `agent`, which is how the Reports picker addresses every
-Proxmox node and standalone agent in v6, carry no alert rows yet:
-`enrichReportRequest` enriches node, VM and container reports only, so an
-agent report's deterministic verdict ignores its machine's alerts (HEALTHY,
-or NO DATA without metrics). The rule above reaches those reports once they
-attach the machine's alerts. The fleet heuristic offers its all-clear
-pattern and "No fleet-wide action required" only while no alert, moved
-ones included, is active.
+The fleet heuristic offers its all-clear pattern and "No fleet-wide action
+required" only while no alert, moved ones included, is active.
+Reports requested as `agent`, which is how the Reports picker addresses
+every Proxmox node and standalone Pulse agent in v6, attach the machine's
+alerts through `enrichAgentReport` in
+`internal/api/reporting_subject_alerts.go`. `reportAlertScopeFor` builds a
+subject's alert identities from its unified resource, never from host or
+node names, and an alert belongs to the report of each resource whose
+identity it was raised under. For a machine that is the requested unified
+ID, the metrics-target ID, the linked Proxmox node's source ID
+(`<instance>-<node>`, the node's own alerts) and, when the agent source is
+present, the Pulse agent's `agent:<host>` alerts with every component child
+the agent raises under that identity (`agent:<host>/disk:...`, disk
+temperature, SMART, RAID, the Unraid array, custom sensors). When the alert
+engine records a node alert's handover to the agent (`moved_to_agent`), the
+moved alert and the agent's own alert for that metric land in one report,
+where the rule above counts them once
+(`TestContract_AgentReportCountsAMovedNodeAlertOnce`). Guests, containers,
+Proxmox storage pools and physical disks raise alerts under their own
+identities, so those stay on their own reports, and a same-named node in
+another cluster never leaks in
+(`TestContract_AgentReportAttachesTheMachinesOwnAlerts`). The one alert
+raised under two identities is the agent's Unraid array alert
+(`agent:<host>/storage:unraid-array`), which appears on both the machine's
+and the array's report. The agent report also fills resource details from
+the resource's Proxmox and agent payloads and lists the storage pools and
+physical disks whose unified parent is the machine through the node
+report's row builders, so a disk shows only a collected temperature,
+coloured by the alert thresholds. Every other type
+without a dedicated enricher attaches the alerts in its scope: the unified
+and metrics-target IDs; `alerts.DockerHostResourceID`,
+`DockerContainerResourceID` and `DockerServiceResourceID` for Docker
+runtimes, containers (by name when they have no ID) and Swarm services; a Proxmox storage pool's source ID with its ZFS pool and device
+children; and the Proxmox health and wearout alerts on a disk's device-path
+reference (`ProxmoxPhysicalDiskAlertResourceID`) through the journal's shared
+recorded-hardware ownership decision (`ProxmoxPhysicalDiskAlertOwner`), not
+through the current device path. Usable serials and WWNs match through
+`diskinventory.HardwareIdentityMatch`, rejecting placeholders and retaining
+cross-source framing. A uniquely shared WWN decides duplicate serials;
+otherwise ambiguous identities are excluded. A row without usable identity
+matches only the single identity-less disk at its exact path. Earlier paths
+and nodes still reach the hardware that owns the alert; a replacement or
+path-shaped metrics alias never overrides ownership. The reference's canonical
+health/wearout alert identifier must also agree
+(`TestReportPhysicalDiskAlertsFollowRecordedHardware`)
+(`TestContract_UnenrichedReportTypesAttachTheSubjectsAlerts`). The legacy
+`node` enricher keeps its name-based match for direct API callers.
+
+`reporting_subject_alerts.go` is an exact shared-default-pipeline exception in
+the Go and shell repository-boundary classifiers, not new migration debt. It
+registers no route, changes no entitlement and imports no private licensing
+implementation. The existing reporting admin binder and execution/scheduling
+licence gates remain in place. `reporting_boundary_test.go` and
+`scripts/repo-boundary-regression.py` run the real Go and shell classifiers
+against the helper, unreviewed neighbouring filenames and private imports:
+neither a prefix exemption nor a licensing-import exemption is allowed. The
+boundary workflow runs the shell controls after installing its declared ripgrep
+dependency; the Go/API suite requires no new external tool.
Multi-resource fleet reports (`engine.GenerateMulti`) now also carry an
optional fleet-level narrative through a distinct
`pkg/reporting.FleetNarrator` interface, kept separate from the
diff --git a/docs/release-control/v6/internal/subsystems/storage-recovery.md b/docs/release-control/v6/internal/subsystems/storage-recovery.md
index 6feadac354..94266c2a5a 100644
--- a/docs/release-control/v6/internal/subsystems/storage-recovery.md
+++ b/docs/release-control/v6/internal/subsystems/storage-recovery.md
@@ -1509,6 +1509,16 @@ recovery scope, or a storage/recovery-owned secret source.
handover resolution (moved to a Pulse agent, not recovered). That changes
how a report states alert health only; it opens no storage, backup or
recovery path, and report backups still come from the recovery store.
+ Machine (`agent`) reports now list the storage pools and physical disks
+ whose unified parent is the machine, through the same row builders as
+ node reports. Storage reports attach their pool's own alerts (the Proxmox
+ source ID plus ZFS pool and device children, or the agent's alert on an
+ Unraid array), and physical-disk reports attach the Proxmox health and
+ wearout alerts owned by the disk's recorded hardware through the journal's
+ shared serial/WWN and ambiguity rules, including earlier paths, rather
+ than inheriting a replacement's current path. All of it reads the existing unified storage
+ and disk projections only; it opens no storage, backup or recovery path
+ and grants no storage action.
Update-plan readiness payloads and apply-route readiness enforcement are
adjacent shared API context only. Storage and recovery surfaces may observe
the resulting update state if a future settings flow links to recovery
diff --git a/docs/release-control/v6/internal/subsystems/unified-resources.md b/docs/release-control/v6/internal/subsystems/unified-resources.md
index a5b1617514..5780e89fc7 100644
--- a/docs/release-control/v6/internal/subsystems/unified-resources.md
+++ b/docs/release-control/v6/internal/subsystems/unified-resources.md
@@ -5963,7 +5963,15 @@ over the path, and disk alerts are evaluated before their poll's disks reach
the registry. A binding belongs to the reference string and would carry every
row and every read of the path to whichever disk held it last. Each lifecycle
row is owned on its own instead (`proxmoxDiskAlertOwner` in
-`internal/unifiedresources/pve_disk_alert_history.go`). The alert records the
+`internal/unifiedresources/pve_disk_alert_history.go`). The same ownership
+decision is exposed on immutable unified snapshots by
+`ProxmoxPhysicalDiskAlertOwner` for subject reports; the registry and snapshot
+entry points share the implementation, including ambiguity, moved paths,
+identity-less fallback and derived-ID collision checks
+(`TestProxmoxDiskAlertOwnerDecisions`). Reporting admits only the reference's
+canonical health/wearout alert identifiers and keeps resolution-window bounds
+(`TestReportPhysicalDiskAlertsFollowRecordedHardware` in `internal/api`).
+The alert records the
evaluated disk's serial and WWN (`disk_serial`, `disk_wwn`), and
`MonitorAdapter.RecordChange` writes the row under the one physical disk the
registry knows by that hardware identity (`diskinventory.HardwareIdentityMatch`),
diff --git a/internal/api/code_standards_test.go b/internal/api/code_standards_test.go
index fd500185ce..cbe2d71320 100644
--- a/internal/api/code_standards_test.go
+++ b/internal/api/code_standards_test.go
@@ -223,6 +223,9 @@ func TestPaidDomainBoundaryAudit(t *testing.T) {
// defaults (the enterprise fork silently drifted and was removed),
// internal/api is the canonical home for the report pipeline.
"reporting_availability.go": true,
+ // Subject identity/alert enrichment for that same default pipeline.
+ // This exact helper adds no endpoint, entitlement or private import.
+ "reporting_subject_alerts.go": true,
}
for name := range goFiles {
diff --git a/internal/api/contract_test.go b/internal/api/contract_test.go
index ff44203a02..1bc1bca9a8 100644
--- a/internal/api/contract_test.go
+++ b/internal/api/contract_test.go
@@ -5049,6 +5049,361 @@ func TestContract_VMInventoryExportCSVHeaders(t *testing.T) {
}
}
+// reportAlertResourceIDs lists a report request's alert rows by resource ID,
+// sorted, so a test can state exactly which alerts a report attributes to
+// its subject.
+func reportAlertResourceIDs(req reporting.MetricReportRequest) []string {
+ ids := make([]string, 0, len(req.Alerts))
+ for _, alert := range req.Alerts {
+ ids = append(ids, alert.ResourceID)
+ }
+ sort.Strings(ids)
+ return ids
+}
+
+// Every Proxmox node and standalone Pulse agent is an `agent` resource in v6,
+// and the Reports picker requests it as one. Its report must carry the
+// machine's own alerts, matched through the identities its unified resource
+// carries: the linked node's source ID, the agent's "agent:<host>" alerts and
+// their component children. Guests, storage pools and same-named nodes in
+// another cluster are not the machine.
+func TestContract_AgentReportAttachesTheMachinesOwnAlerts(t *testing.T) {
+ now := time.Now()
+ start := now.Add(-24 * time.Hour)
+ machineID := "agent-west-a"
+ memoryTotal, diskTotal := int64(64<<30), int64(1<<40)
+ storageTotal, storageUsed := int64(2<<40), int64(1<<40)
+ snapshot := reportingEnrichmentSnapshot{
+ Resources: []unifiedresources.Resource{
+ {
+ ID: machineID,
+ Type: unifiedresources.ResourceTypeAgent,
+ Name: "West Production A",
+ Status: unifiedresources.StatusOnline,
+ Uptime: 86400,
+ Sources: []unifiedresources.DataSource{unifiedresources.SourceProxmox, unifiedresources.SourceAgent},
+ Identity: unifiedresources.ResourceIdentity{
+ IPAddresses: []string{"192.0.2.10"},
+ },
+ Metrics: &unifiedresources.ResourceMetrics{
+ Memory: &unifiedresources.MetricValue{Total: &memoryTotal},
+ Disk: &unifiedresources.MetricValue{Total: &diskTotal},
+ },
+ Proxmox: &unifiedresources.ProxmoxData{
+ SourceID: "cluster-a-pve1",
+ NodeName: "pve1",
+ Instance: "cluster-a",
+ HostURL: "https://pve1.example:8006",
+ PVEVersion: "8.2.4",
+ KernelVersion: "6.8.12-1-pve",
+ ClusterName: "cluster-a",
+ CPUInfo: &unifiedresources.CPUInfo{Model: "Xeon E5-2680", Cores: 16, Sockets: 2},
+ },
+ Agent: &unifiedresources.AgentData{
+ AgentID: "host-pve1",
+ OSName: "Debian GNU/Linux",
+ OSVersion: "12",
+ },
+ },
+ {
+ ID: "storage-west-a-zfs",
+ Type: unifiedresources.ResourceTypeStorage,
+ Name: "local-zfs",
+ Status: unifiedresources.StatusOnline,
+ ParentID: &machineID,
+ Metrics: &unifiedresources.ResourceMetrics{
+ Disk: &unifiedresources.MetricValue{Total: &storageTotal, Used: &storageUsed, Percent: 50},
+ },
+ Storage: &unifiedresources.StorageMeta{Type: "zfspool", Content: "images"},
+ Proxmox: &unifiedresources.ProxmoxData{SourceID: "cluster-a-pve1-local-zfs"},
+ },
+ {
+ ID: "physical-disk-west-a-nvme0",
+ Type: unifiedresources.ResourceTypePhysicalDisk,
+ ParentID: &machineID,
+ PhysicalDisk: &unifiedresources.PhysicalDiskMeta{DevPath: "/dev/nvme0n1", Model: "Samsung 990", DiskType: "nvme", Health: "PASSED", Temperature: 41},
+ },
+ {
+ // A disk in standby keeps its last-known temperature, which a
+ // report must not tabulate as measured.
+ ID: "physical-disk-west-a-sdb",
+ Type: unifiedresources.ResourceTypePhysicalDisk,
+ ParentID: &machineID,
+ PhysicalDisk: &unifiedresources.PhysicalDiskMeta{
+ DevPath: "/dev/sdb", DiskType: "hdd", Health: "PASSED", Temperature: 52,
+ Collection: &diskinventory.CollectionStatus{
+ Temperature: diskinventory.FieldStatus{State: diskinventory.FieldUnavailable, Reason: "standby"},
+ },
+ },
+ },
+ {
+ ID: "vm-west-a-101",
+ Type: unifiedresources.ResourceTypeVM,
+ ParentID: &machineID,
+ },
+ },
+ ActiveAlerts: []models.Alert{
+ // The node's own alert, keyed by the Proxmox source ID.
+ {ID: "node-cpu", Type: "cpu", Level: "critical", ResourceID: "cluster-a-pve1", Node: "pve1", StartTime: now.Add(-time.Hour)},
+ // The agent's own alert and a filesystem it reports.
+ {ID: "agent-memory", Type: "memory", Level: "warning", ResourceID: "agent:host-pve1", Node: "pve1", StartTime: now.Add(-time.Hour)},
+ {ID: "agent-disk", Type: "disk", Level: "warning", ResourceID: "agent:host-pve1/disk:/", Node: "pve1", StartTime: now.Add(-time.Hour)},
+ // The agent raises its Unraid array alert under its own identity,
+ // so it belongs to the machine as well as to the array's report.
+ {ID: "agent-array", Type: "unraid-array", Level: "warning", ResourceID: "agent:host-pve1/storage:unraid-array", Node: "pve1", StartTime: now.Add(-time.Hour)},
+ // A provider incident keyed by the unified ID.
+ {ID: "incident", Type: "resource-incident", Level: "warning", ResourceID: machineID, StartTime: now.Add(-time.Hour)},
+ // Not the machine: a guest, a storage pool, a same-named node in
+ // another cluster, and an agent whose host ID shares a prefix.
+ {ID: "guest", Type: "powered-off", Level: "warning", ResourceID: "cluster-a-pve1-101", Node: "pve1", StartTime: now.Add(-time.Hour)},
+ {ID: "pool", Type: "zfs-pool-errors", Level: "warning", ResourceID: "cluster-a-pve1-local-zfs/zfs-pool:local-zfs", Node: "pve1", StartTime: now.Add(-time.Hour)},
+ {ID: "other-cluster", Type: "cpu", Level: "critical", ResourceID: "cluster-b-pve1", Node: "pve1", StartTime: now.Add(-time.Hour)},
+ {ID: "other-agent", Type: "memory", Level: "critical", ResourceID: "agent:host-pve10", Node: "pve10", StartTime: now.Add(-time.Hour)},
+ },
+ RecentlyResolved: []models.ResolvedAlert{
+ {
+ Alert: models.Alert{ID: "node-temp", Type: "temperature", Level: "warning", ResourceID: "cluster-a-pve1", Node: "pve1", StartTime: now.Add(-3 * time.Hour)},
+ ResolvedTime: now.Add(-2 * time.Hour),
+ },
+ {
+ Alert: models.Alert{ID: "node-old", Type: "cpu", Level: "warning", ResourceID: "cluster-a-pve1", Node: "pve1", StartTime: now.Add(-50 * time.Hour)},
+ ResolvedTime: now.Add(-48 * time.Hour),
+ },
+ },
+ }
+
+ req := reporting.MetricReportRequest{ResourceType: "agent", ResourceID: machineID}
+ NewReportingHandlers(nil, nil).enrichReportRequest(context.Background(), "default", &req, snapshot, start, now)
+
+ wantAlerts := []string{"agent-west-a", "agent:host-pve1", "agent:host-pve1/disk:/", "agent:host-pve1/storage:unraid-array", "cluster-a-pve1", "cluster-a-pve1"}
+ if got := reportAlertResourceIDs(req); !reflect.DeepEqual(got, wantAlerts) {
+ t.Fatalf("agent report alerts = %v, want %v", got, wantAlerts)
+ }
+ for _, alert := range req.Alerts {
+ if alert.Type == "temperature" && (alert.ResolvedTime == nil || !alert.Recovered()) {
+ t.Fatalf("node alert resolved inside the window must read as a recovery, got %+v", alert)
+ }
+ }
+
+ res := req.Resource
+ if res == nil {
+ t.Fatal("agent report carries no resource details")
+ }
+ if res.Name != "West Production A" || res.Host != "https://pve1.example:8006" || res.PVEVersion != "8.2.4" ||
+ res.KernelVersion != "6.8.12-1-pve" || res.CPUModel != "Xeon E5-2680" || res.CPUCores != 16 || res.CPUSockets != 2 ||
+ res.MemoryTotal != memoryTotal || res.DiskTotal != diskTotal || res.Uptime != 86400 ||
+ res.OSName != "Debian GNU/Linux" || res.OSVersion != "12" || res.ClusterName != "cluster-a" ||
+ !reflect.DeepEqual(res.IPAddresses, []string{"192.0.2.10"}) {
+ t.Fatalf("agent report resource details = %+v", res)
+ }
+ if len(req.Storage) != 1 || req.Storage[0].Name != "local-zfs" || req.Storage[0].Type != "zfspool" || req.Storage[0].UsagePerc != 50 {
+ t.Fatalf("agent report storage = %+v", req.Storage)
+ }
+ // Disk rows share the node report's builder: only a collected temperature
+ // is tabulated, coloured by the disk temperature alert thresholds.
+ if len(req.Disks) != 2 {
+ t.Fatalf("agent report disks = %+v", req.Disks)
+ }
+ nvme, standby := req.Disks[0], req.Disks[1]
+ if nvme.Device != "/dev/nvme0n1" || nvme.Health != "PASSED" || nvme.Temperature != 41 ||
+ nvme.TemperatureCritical <= 0 || nvme.TemperatureWarning <= 0 || nvme.TemperatureWarning > nvme.TemperatureCritical {
+ t.Fatalf("collected disk row = %+v", nvme)
+ }
+ if standby.Device != "/dev/sdb" || standby.Temperature != 0 {
+ t.Fatalf("a retained disk temperature must not be reported as measured, got %+v", standby)
+ }
+}
+
+// A node alert that moved to the machine's Pulse agent and the agent's own
+// alert for that metric both belong to the machine's report, and the report
+// verdict counts the condition once.
+func TestContract_AgentReportCountsAMovedNodeAlertOnce(t *testing.T) {
+ now := time.Now()
+ machineID := "agent-west-a"
+ snapshot := reportingEnrichmentSnapshot{
+ Resources: []unifiedresources.Resource{{
+ ID: machineID,
+ Type: unifiedresources.ResourceTypeAgent,
+ Name: "West Production A",
+ Sources: []unifiedresources.DataSource{unifiedresources.SourceProxmox, unifiedresources.SourceAgent},
+ Proxmox: &unifiedresources.ProxmoxData{SourceID: "cluster-a-pve1", NodeName: "pve1"},
+ Agent: &unifiedresources.AgentData{AgentID: "host-pve1"},
+ }},
+ ActiveAlerts: []models.Alert{{
+ ID: "agent-memory", Type: "memory", Level: "warning", ResourceID: "agent:host-pve1",
+ Message: "Agent memory at 94%", StartTime: now.Add(-time.Minute),
+ }},
+ RecentlyResolved: []models.ResolvedAlert{{
+ Alert: models.Alert{
+ ID: "node-memory", Type: "memory", Level: "warning", ResourceID: "cluster-a-pve1",
+ Message: "Node memory at 95%", StartTime: now.Add(-time.Hour),
+ Resolution: &models.AlertResolution{
+ Reason: "moved_to_agent",
+ SuccessorResourceID: "agent:host-pve1",
+ SuccessorName: "pve1 (Host Agent)",
+ },
+ },
+ ResolvedTime: now.Add(-2 * time.Minute),
+ }},
+ }
+
+ req := reporting.MetricReportRequest{ResourceType: "agent", ResourceID: machineID}
+ NewReportingHandlers(nil, nil).enrichReportRequest(context.Background(), "default", &req, snapshot, now.Add(-24*time.Hour), now)
+
+ if got := reportAlertResourceIDs(req); !reflect.DeepEqual(got, []string{"agent:host-pve1", "cluster-a-pve1"}) {
+ t.Fatalf("agent report alerts = %v", got)
+ }
+ narrative, err := reporting.HeuristicNarrator{}.Narrate(context.Background(), reporting.NarrativeInput{Alerts: req.Alerts})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if narrative.HealthStatus != "WARNING" || narrative.HealthMessage != "1 warning detected - review recommended" {
+ t.Fatalf("moved node alert and its successor must count once, got %q / %q", narrative.HealthStatus, narrative.HealthMessage)
+ }
+}
+
+// Report types without a dedicated enricher still list the alerts raised on
+// their subject: the unified ID, the metrics-target ID, and the IDs each
+// alert producer builds for a Docker runtime, a container or a storage pool's
+// ZFS components. Workloads under a runtime stay with their own reports.
+func TestContract_UnenrichedReportTypesAttachTheSubjectsAlerts(t *testing.T) {
+ now := time.Now()
+ resources := []unifiedresources.Resource{
+ {
+ // Docker runtimes are agent-typed internally and travel as
+ // docker-host.
+ ID: "agent-docker-1",
+ Type: unifiedresources.ResourceTypeAgent,
+ Sources: []unifiedresources.DataSource{unifiedresources.SourceDocker},
+ Docker: &unifiedresources.DockerData{HostSourceID: "docker-host-1"},
+ },
+ {
+ ID: "app-container-web",
+ Type: unifiedresources.ResourceTypeAppContainer,
+ Name: "web",
+ Sources: []unifiedresources.DataSource{unifiedresources.SourceDocker},
+ Docker: &unifiedresources.DockerData{HostSourceID: "docker-host-1", ContainerID: "web-1"},
+ },
+ {
+ // A container reported without an ID is referenced by its name.
+ ID: "app-container-sidecar",
+ Type: unifiedresources.ResourceTypeAppContainer,
+ Name: "sidecar",
+ Sources: []unifiedresources.DataSource{unifiedresources.SourceDocker},
+ Docker: &unifiedresources.DockerData{HostSourceID: "docker-host-1"},
+ },
+ {
+ ID: "storage-zfs",
+ Type: unifiedresources.ResourceTypeStorage,
+ Sources: []unifiedresources.DataSource{unifiedresources.SourceProxmox},
+ Proxmox: &unifiedresources.ProxmoxData{SourceID: "cluster-a-pve1-local-zfs"},
+ },
+ {
+ ID: "k8s-cluster-prod",
+ Type: unifiedresources.ResourceTypeK8sCluster,
+ },
+ {
+ ID: "pmg-eu",
+ Type: unifiedresources.ResourceTypePMG,
+ MetricsTarget: &unifiedresources.MetricsTarget{ResourceType: "agent", ResourceID: "pmg-main"},
+ },
+ {
+ ID: "docker-service-web",
+ Type: unifiedresources.ResourceTypeDockerService,
+ Sources: []unifiedresources.DataSource{unifiedresources.SourceDocker},
+ Docker: &unifiedresources.DockerData{HostSourceID: "docker-host-1", ServiceID: "svc-1"},
+ },
+ {
+ // A service without an ID is named by the adapter's resource
+ // name, which the producer falls back to.
+ ID: "docker-service-api",
+ Type: unifiedresources.ResourceTypeDockerService,
+ Name: "api",
+ Sources: []unifiedresources.DataSource{unifiedresources.SourceDocker},
+ Docker: &unifiedresources.DockerData{HostSourceID: "docker-host-1"},
+ },
+ {
+ // A Pulse agent reports the Unraid array as storage keyed by
+ // its own source ID, which is the metrics target.
+ ID: "storage-unraid",
+ Type: unifiedresources.ResourceTypeStorage,
+ Sources: []unifiedresources.DataSource{unifiedresources.SourceAgent},
+ MetricsTarget: &unifiedresources.MetricsTarget{ResourceType: "storage", ResourceID: "host-1/storage:unraid-array"},
+ },
+ {
+ ID: "physical-disk-sda",
+ Type: unifiedresources.ResourceTypePhysicalDisk,
+ Sources: []unifiedresources.DataSource{unifiedresources.SourceProxmox},
+ Proxmox: &unifiedresources.ProxmoxData{Instance: "cluster-a", NodeName: "pve1"},
+ PhysicalDisk: &unifiedresources.PhysicalDiskMeta{DevPath: "/dev/sda", Serial: "SER-B"},
+ },
+ }
+ active := func(resourceID string) models.Alert {
+ return models.Alert{ID: resourceID + "-alert", Type: "status", Level: "warning", ResourceID: resourceID, StartTime: now.Add(-time.Hour)}
+ }
+ // Proxmox disk alerts reference the device path, which a replacement disk
+ // in the same slot takes over, and record the serial of the disk they
+ // were raised on.
+ diskRef := unifiedresources.ProxmoxPhysicalDiskAlertResourceID("cluster-a", "pve1", "/dev/sda")
+ diskAlert := func(id, serial string) models.Alert {
+ alert := active(diskRef)
+ alert.ID, alert.Type, alert.Message = unifiedresources.ProxmoxPhysicalDiskAlertIdentifiers(diskRef)[0], "disk-health", id
+ alert.Metadata = map[string]interface{}{"disk_serial": serial}
+ return alert
+ }
+ snapshot := reportingEnrichmentSnapshot{
+ Resources: resources,
+ ActiveAlerts: []models.Alert{
+ active(alerts.DockerHostResourceID("docker-host-1")),
+ active(alerts.DockerContainerResourceID("docker-host-1", "web-1", "web")),
+ active(alerts.DockerContainerResourceID("docker-host-1", "", "sidecar")),
+ active("cluster-a-pve1-local-zfs"),
+ active("cluster-a-pve1-local-zfs/zfs-pool:local-zfs"),
+ active("cluster-a-pve1-local-zfs/zfs-pool:local-zfs/device:sda2"),
+ active("cluster-a-pve1-local-zfs2"),
+ active("k8s-cluster-prod"),
+ active("pmg-main"),
+ active(alerts.DockerServiceResourceID("docker-host-1", "svc-1", "web")),
+ active(alerts.DockerServiceResourceID("docker-host-1", "", "api")),
+ active("agent:host-1/storage:unraid-array"),
+ diskAlert("disk-health-replacement", "SER-B"),
+ diskAlert("disk-health-predecessor", "SER-A"),
+ },
+ }
+
+ for _, tc := range []struct {
+ resourceType string
+ resourceID string
+ want []string
+ }{
+ {"docker-host", "agent-docker-1", []string{alerts.DockerHostResourceID("docker-host-1")}},
+ {"app-container", "app-container-web", []string{alerts.DockerContainerResourceID("docker-host-1", "web-1", "web")}},
+ {"app-container", "app-container-sidecar", []string{alerts.DockerContainerResourceID("docker-host-1", "", "sidecar")}},
+ {"storage", "storage-zfs", []string{
+ "cluster-a-pve1-local-zfs",
+ "cluster-a-pve1-local-zfs/zfs-pool:local-zfs",
+ "cluster-a-pve1-local-zfs/zfs-pool:local-zfs/device:sda2",
+ }},
+ {"k8s", "k8s-cluster-prod", []string{"k8s-cluster-prod"}},
+ {"pmg", "pmg-eu", []string{"pmg-main"}},
+ {"app-container", "docker-service-web", []string{alerts.DockerServiceResourceID("docker-host-1", "svc-1", "web")}},
+ {"app-container", "docker-service-api", []string{alerts.DockerServiceResourceID("docker-host-1", "", "api")}},
+ {"storage", "storage-unraid", []string{"agent:host-1/storage:unraid-array"}},
+ {"disk", "physical-disk-sda", []string{diskRef}},
+ } {
+ req := reporting.MetricReportRequest{ResourceType: tc.resourceType, ResourceID: tc.resourceID}
+ NewReportingHandlers(nil, nil).enrichReportRequest(context.Background(), "default", &req, snapshot, now.Add(-24*time.Hour), now)
+ if got := reportAlertResourceIDs(req); !reflect.DeepEqual(got, tc.want) {
+ t.Fatalf("%s report alerts = %v, want %v", tc.resourceType, got, tc.want)
+ }
+ // Only the alert naming the replacement disk's serial is its own;
+ // its predecessor's alert on the same path stays off its report.
+ if tc.resourceType == "disk" && req.Alerts[0].Message != "disk-health-replacement" {
+ t.Fatalf("disk report alert = %+v", req.Alerts[0])
+ }
+ }
+}
+
func TestContract_ReportingCatalogJSONSnapshot(t *testing.T) {
handler := NewReportingHandlers(nil, nil)
req := httptest.NewRequest(http.MethodGet, "/api/admin/reports/catalog", nil)
diff --git a/internal/api/metrics_reporting_handlers.go b/internal/api/metrics_reporting_handlers.go
index 08e4c7b240..201c3b110e 100644
--- a/internal/api/metrics_reporting_handlers.go
+++ b/internal/api/metrics_reporting_handlers.go
@@ -694,6 +694,10 @@ func (h *ReportingHandlers) enrichReportRequest(ctx context.Context, orgID strin
h.enrichVMReport(ctx, orgID, req, snapshot, start, end)
case "system-container", "oci-container":
h.enrichContainerReport(ctx, orgID, req, snapshot, start, end)
+ case "agent":
+ h.enrichAgentReport(req, snapshot, start, end)
+ default:
+ attachReportAlerts(req, snapshot, reportAlertScopeFor(req, findReportSubjectResource(req, snapshot)), start, end)
}
}
@@ -849,41 +853,7 @@ func (h *ReportingHandlers) enrichNodeReport(req *reporting.MetricReportRequest,
if storageNode != node.Name {
continue
}
-
- var total, used, available int64
- var usagePerc float64
- if r.Metrics != nil && r.Metrics.Disk != nil {
- if r.Metrics.Disk.Total != nil {
- total = *r.Metrics.Disk.Total
- }
- if r.Metrics.Disk.Used != nil {
- used = *r.Metrics.Disk.Used
- }
- if total > 0 {
- available = total - used
- }
- usagePerc = r.Metrics.Disk.Percent
- if usagePerc == 0 && total > 0 {
- usagePerc = (float64(used) / float64(total)) * 100
- }
- }
-
- var storageType, content string
- if r.Storage != nil {
- storageType = r.Storage.Type
- content = r.Storage.Content
- }
-
- req.Storage = append(req.Storage, reporting.StorageInfo{
- Name: r.Name,
- Type: storageType,
- Status: string(r.Status),
- Total: total,
- Used: used,
- Available: available,
- UsagePerc: usagePerc,
- Content: content,
- })
+ req.Storage = append(req.Storage, reportStorageInfo(r))
case unifiedresources.ResourceTypePhysicalDisk:
if r.PhysicalDisk == nil {
continue
@@ -895,20 +865,7 @@ func (h *ReportingHandlers) enrichNodeReport(req *reporting.MetricReportRequest,
if diskNode != node.Name {
continue
}
- pd := r.PhysicalDisk
- temperatureWarning, temperatureCritical := reportDiskTemperatureThresholds(snapshot.alertManager, pd.DiskType)
- req.Disks = append(req.Disks, reporting.DiskInfo{
- Device: pd.DevPath,
- Model: pd.Model,
- Serial: pd.Serial,
- Type: pd.DiskType,
- Size: pd.SizeBytes,
- Health: pd.Health,
- Temperature: reportDiskTemperature(*pd),
- WearLevel: pd.Wearout,
- TemperatureWarning: temperatureWarning,
- TemperatureCritical: temperatureCritical,
- })
+ req.Disks = append(req.Disks, reportDiskInfo(*r.PhysicalDisk, snapshot.alertManager))
}
}
}
diff --git a/internal/api/reporting_boundary_test.go b/internal/api/reporting_boundary_test.go
new file mode 100644
index 0000000000..e7e35cc24d
--- /dev/null
+++ b/internal/api/reporting_boundary_test.go
@@ -0,0 +1,114 @@
+package api
+
+import (
+ "context"
+ "io/fs"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+)
+
+// Exercise the production Go classifiers, not a second copy of their patterns.
+// The shell classifier is exercised in scripts/repo-boundary-regression.py,
+// where the boundary workflow supplies its declared ripgrep dependency.
+// An exact shared-pipeline exemption must not admit neighbouring implementation
+// files or let the exempt helper import private licensing code.
+func TestReportingSubjectBoundaryExemptionIsExact(t *testing.T) {
+ binary, err := os.Executable()
+ if err != nil {
+ t.Fatal(err)
+ }
+ repo := filepath.Join("..", "..")
+ for _, tc := range []struct {
+ name, file, content, goMarker string
+ }{
+ {name: "shared subject pipeline"},
+ {
+ name: "new reporting implementation", file: "reporting_subject_alerts_extra.go", content: "package api\n",
+ goMarker: "untracked paid-domain file reporting_subject_alerts_extra.go",
+ },
+ {
+ name: "exact path not prefix", file: "reporting_subject_alerts.go.extra.go", content: "package api\n",
+ goMarker: "untracked paid-domain file reporting_subject_alerts.go.extra.go",
+ },
+ {
+ name: "private root import still denied", file: "reporting_subject_alerts.go",
+ content: "package api\nimport _ \"github.com/rcourtman/pulse-go-rewrite/internal/license\"\n",
+ goMarker: "direct internal/license import",
+ },
+ {
+ name: "licensing bridge still required", file: "reporting_subject_alerts.go",
+ content: "package api\nimport _ \"github.com/rcourtman/pulse-go-rewrite/pkg/licensing\"\n",
+ goMarker: "reporting_subject_alerts.go",
+ },
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ root := t.TempDir()
+ for _, dir := range []string{"internal/api"} {
+ err := filepath.WalkDir(filepath.Join(repo, dir), func(path string, entry fs.DirEntry, err error) error {
+ if err != nil {
+ return err
+ }
+ if entry.IsDir() || !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+ return nil
+ }
+ rel, err := filepath.Rel(repo, path)
+ if err != nil {
+ return err
+ }
+ copyReportingBoundaryFile(t, path, filepath.Join(root, rel))
+ return nil
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ }
+ apiDir := filepath.Join(root, "internal/api")
+ if tc.file != "" {
+ if err := os.WriteFile(filepath.Join(apiDir, tc.file), []byte(tc.content), 0600); err != nil {
+ t.Fatal(err)
+ }
+ }
+ // The running test binary scans fixture bytes; injected files are
+ // never compiled or executed. The anchored selector prevents recursion.
+ runReportingBoundaryCommand(t, apiDir, tc.goMarker, binary,
+ "-test.run=^(TestPaidDomainBoundaryAudit|TestNoInternalLicenseImportFromAPIProd|TestPkgLicensingImportBoundary)$", "-test.v")
+ })
+ }
+}
+
+func copyReportingBoundaryFile(t *testing.T, source, target string) {
+ t.Helper()
+ data, err := os.ReadFile(source)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := os.MkdirAll(filepath.Dir(target), 0700); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(target, data, 0600); err != nil {
+ t.Fatal(err)
+ }
+}
+
+func runReportingBoundaryCommand(t *testing.T, dir, rejection, command string, args ...string) {
+ t.Helper()
+ ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+ defer cancel()
+ cmd := exec.CommandContext(ctx, command, args...)
+ cmd.Dir = dir
+ output, err := cmd.CombinedOutput()
+ if rejection == "" {
+ if err != nil {
+ t.Fatalf("shared pipeline rejected by %s: %v\n%s", command, err, output)
+ }
+ return
+ }
+ exit, ok := err.(*exec.ExitError)
+ if !ok || exit.ExitCode() != 1 || !strings.Contains(string(output), rejection) {
+ t.Fatalf("%s rejection = %v / %s, want exit 1 containing %q", command, err, output, rejection)
+ }
+}
diff --git a/internal/api/reporting_subject_alerts.go b/internal/api/reporting_subject_alerts.go
new file mode 100644
index 0000000000..ebff39e2d3
--- /dev/null
+++ b/internal/api/reporting_subject_alerts.go
@@ -0,0 +1,355 @@
+package api
+
+import (
+ "slices"
+ "strings"
+ "time"
+
+ "github.com/rcourtman/pulse-go-rewrite/internal/alerts"
+ "github.com/rcourtman/pulse-go-rewrite/internal/models"
+ "github.com/rcourtman/pulse-go-rewrite/internal/unifiedresources"
+ "github.com/rcourtman/pulse-go-rewrite/pkg/reporting"
+)
+
+// reportAlertScope is the set of alert resource IDs a report attributes to
+// its subject. It is built from the identities the subject's unified
+// resource carries, never from host or node names: an alert belongs to the
+// report of each resource whose identity it was raised under. A machine's
+// report therefore leaves out the guests, containers, storage pools and
+// disks it hosts, whose alerts are raised under their own identities and
+// appear on their own reports.
+type reportAlertScope struct {
+ ids map[string]struct{}
+ // childPrefixes match component alerts raised under the subject's own
+ // alert identity, such as "agent:<host>/disk:/" for a filesystem the
+ // agent reports.
+ childPrefixes []string
+ // PVE disk alerts are owned by their recorded hardware, across old and
+ // current paths. Use the journal's ownership rule on this report snapshot.
+ pveDiskID string
+}
+
+func (s *reportAlertScope) addID(id string) {
+ if id = strings.TrimSpace(id); id != "" {
+ s.ids[id] = struct{}{}
+ }
+}
+
+func (s *reportAlertScope) addChildPrefix(parentID string) {
+ if parentID = strings.TrimSpace(parentID); parentID != "" {
+ s.childPrefixes = append(s.childPrefixes, parentID+"/")
+ }
+}
+
+// matchesAlert reports whether an alert belongs to the subject.
+func (s reportAlertScope) matchesAlert(alert models.Alert, resources []unifiedresources.Resource) bool {
+ ref := strings.TrimSpace(alert.ResourceID)
+ if s.pveDiskID != "" {
+ identifiers := unifiedresources.ProxmoxPhysicalDiskAlertIdentifiers(ref)
+ if len(identifiers) > 0 {
+ // A request/metrics alias equal to the path cannot bypass hardware
+ // ownership. Only this reference's actual PVE alerts enter the gate.
+ return slices.Contains(identifiers, alert.ID) &&
+ unifiedresources.ProxmoxPhysicalDiskAlertOwner(ref, alert.Metadata, resources) == s.pveDiskID
+ }
+ }
+ return s.matches(ref)
+}
+
+func (s reportAlertScope) matches(resourceID string) bool {
+ resourceID = strings.TrimSpace(resourceID)
+ if resourceID == "" {
+ return false
+ }
+ if _, ok := s.ids[resourceID]; ok {
+ return true
+ }
+ for _, prefix := range s.childPrefixes {
+ if strings.HasPrefix(resourceID, prefix) {
+ return true
+ }
+ }
+ return false
+}
+
+// reportAlertScopeFor returns the alert identities of a report subject:
+// - the requested unified ID and the resource's metrics-target ID, which
+// key provider incidents and the alerts evaluated on unified resources
+// (vSphere hosts, TrueNAS systems, Kubernetes, PBS, PMG);
+// - for a machine, its linked Proxmox node's source ID
+// ("<instance>-<node>"), which keys the node's own alerts, and its
+// Pulse agent's "agent:<host>" alerts with their component children
+// ("agent:<host>/disk:<mount>", disk temperature, SMART, RAID, the Unraid
+// array, custom sensors). A node alert that moved to the agent and the
+// agent's own alert for that metric therefore land in the same report,
+// where pkg/reporting counts them once;
+// - for a Docker runtime, container or Swarm service, the IDs the Docker
+// alert producer builds (alerts.DockerHostResourceID,
+// DockerContainerResourceID, DockerServiceResourceID);
+// - for a storage pool, its source ID and the pool's ZFS components
+// ("<storage>/zfs-pool:<pool>/device:<dev>"), or for an agent-reported
+// Unraid array, the agent alert raised on it;
+// - for a physical disk, PVE health/wearout alerts whose recorded hardware
+// owns the subject in the unified snapshot, even after a path move.
+//
+// resource may be nil when the request names no live unified resource; the
+// scope then holds only the request's own IDs.
+func reportAlertScopeFor(req *reporting.MetricReportRequest, resource *unifiedresources.Resource) reportAlertScope {
+ scope := reportAlertScope{ids: make(map[string]struct{})}
+ if req != nil {
+ scope.addID(req.ResourceID)
+ scope.addID(req.MetricsResourceID)
+ }
+ if resource == nil {
+ return scope
+ }
+ scope.addID(resource.ID)
+ switch unifiedresources.CanonicalResourceType(resource.Type) {
+ case unifiedresources.ResourceTypeAgent:
+ if resource.Proxmox != nil {
+ scope.addID(resource.Proxmox.SourceID)
+ }
+ if agentID := reportHostAgentID(*resource); agentID != "" {
+ // Alert evaluation names a Pulse agent "agent:<host ID>"
+ // (alerts.hostResourceID), the same reference the canonical
+ // identity indexes for per-resource policy (#1497).
+ scope.addID("agent:" + agentID)
+ scope.addChildPrefix("agent:" + agentID)
+ }
+ if resource.Docker != nil && strings.TrimSpace(resource.Docker.HostSourceID) != "" {
+ scope.addID(alerts.DockerHostResourceID(resource.Docker.HostSourceID))
+ }
+ case unifiedresources.ResourceTypeAppContainer:
+ if docker := resource.Docker; docker != nil && strings.TrimSpace(docker.HostSourceID) != "" {
+ // A container without an ID is referenced by its name, which
+ // the container adapter carries as the resource name.
+ scope.addID(alerts.DockerContainerResourceID(docker.HostSourceID, docker.ContainerID, resource.Name))
+ }
+ case unifiedresources.ResourceTypeDockerService:
+ if docker := resource.Docker; docker != nil && strings.TrimSpace(docker.HostSourceID) != "" {
+ // The service adapter carries the service name as the resource
+ // name; the producer falls back to it when the ID is empty.
+ serviceName := docker.ServiceName
+ if strings.TrimSpace(serviceName) == "" {
+ serviceName = resource.Name
+ }
+ scope.addID(alerts.DockerServiceResourceID(docker.HostSourceID, docker.ServiceID, serviceName))
+ }
+ case unifiedresources.ResourceTypeStorage:
+ if resource.Proxmox != nil {
+ scope.addID(resource.Proxmox.SourceID)
+ scope.addChildPrefix(resource.Proxmox.SourceID)
+ }
+ // A Pulse agent reports an Unraid array as storage keyed
+ // "<host>/storage:unraid-array", which is then the metrics target, and
+ // raises the array's alert under its own identity as
+ // "agent:<host>/storage:unraid-array". That alert belongs to both the
+ // array's report and its machine's.
+ if req != nil && reportStorageReportedOnlyByAgent(*resource) && strings.TrimSpace(req.MetricsResourceID) != "" {
+ scope.addID("agent:" + strings.TrimSpace(req.MetricsResourceID))
+ }
+ case unifiedresources.ResourceTypePhysicalDisk:
+ scope.pveDiskID = resource.ID
+ }
+ return scope
+}
+
+// reportStorageReportedOnlyByAgent reports whether a storage resource comes
+// from a Pulse agent alone, so its metrics target is the agent's source ID.
+func reportStorageReportedOnlyByAgent(resource unifiedresources.Resource) bool {
+ if !slices.Contains(resource.Sources, unifiedresources.SourceAgent) {
+ return false
+ }
+ for _, source := range resource.Sources {
+ if source != unifiedresources.SourceAgent {
+ return false
+ }
+ }
+ return true
+}
+
+// reportHostAgentID is the host ID of the Pulse agent reporting a machine.
+// vSphere hosts and TrueNAS systems also fill AgentData, so the agent source
+// must be present before the ID names a Pulse agent.
+func reportHostAgentID(resource unifiedresources.Resource) string {
+ if resource.Agent == nil || !slices.Contains(resource.Sources, unifiedresources.SourceAgent) {
+ return ""
+ }
+ return strings.TrimSpace(resource.Agent.AgentID)
+}
+
+// findReportSubjectResource returns the unified resource the request names.
+func findReportSubjectResource(req *reporting.MetricReportRequest, snapshot reportingEnrichmentSnapshot) *unifiedresources.Resource {
+ if req == nil {
+ return nil
+ }
+ for i := range snapshot.Resources {
+ if snapshot.Resources[i].ID == req.ResourceID {
+ return &snapshot.Resources[i]
+ }
+ }
+ return nil
+}
+
+// attachReportAlerts adds the subject's open alerts and the alerts resolved
+// inside the report window, keeping each alert's resolution.
+func attachReportAlerts(req *reporting.MetricReportRequest, snapshot reportingEnrichmentSnapshot, scope reportAlertScope, start, end time.Time) {
+ for _, alert := range snapshot.ActiveAlerts {
+ if scope.matchesAlert(alert, snapshot.Resources) {
+ req.Alerts = append(req.Alerts, reportActiveAlertInfo(alert))
+ }
+ }
+ for _, resolved := range snapshot.RecentlyResolved {
+ if scope.matchesAlert(resolved.Alert, snapshot.Resources) &&
+ resolved.ResolvedTime.After(start) && resolved.ResolvedTime.Before(end) {
+ req.Alerts = append(req.Alerts, reportResolvedAlertInfo(resolved))
+ }
+ }
+}
+
+// enrichAgentReport fills a report on a machine: every Proxmox node and
+// standalone Pulse agent is a unified `agent` resource in v6. Details come
+// from the resource's Proxmox and agent payloads, storage pools and physical
+// disks from the resources whose unified parent is the machine, and alerts
+// from reportAlertScopeFor.
+func (h *ReportingHandlers) enrichAgentReport(req *reporting.MetricReportRequest, snapshot reportingEnrichmentSnapshot, start, end time.Time) {
+ resource := findReportSubjectResource(req, snapshot)
+ if resource != nil {
+ req.Resource = reportMachineResourceInfo(*resource)
+ for i := range snapshot.Resources {
+ child := &snapshot.Resources[i]
+ if child.ParentID == nil || *child.ParentID != resource.ID {
+ continue
+ }
+ switch unifiedresources.CanonicalResourceType(child.Type) {
+ case unifiedresources.ResourceTypeStorage:
+ req.Storage = append(req.Storage, reportStorageInfo(*child))
+ case unifiedresources.ResourceTypePhysicalDisk:
+ if child.PhysicalDisk != nil {
+ req.Disks = append(req.Disks, reportDiskInfo(*child.PhysicalDisk, snapshot.alertManager))
+ }
+ }
+ }
+ }
+ attachReportAlerts(req, snapshot, reportAlertScopeFor(req, resource), start, end)
+}
+
+// reportMachineResourceInfo projects a machine's unified payloads onto the
+// report's resource details. The Proxmox API is authoritative for PVE
+// facts; the Pulse agent adds the operating system.
+func reportMachineResourceInfo(resource unifiedresources.Resource) *reporting.ResourceInfo {
+ info := &reporting.ResourceInfo{
+ Name: resource.Name,
+ Status: string(resource.Status),
+ Uptime: resource.Uptime,
+ IPAddresses: append([]string(nil), resource.Identity.IPAddresses...),
+ Tags: append([]string(nil), resource.Tags...),
+ }
+ if resource.Temperature != nil {
+ temp := *resource.Temperature
+ info.Temperature = &temp
+ }
+ if metrics := resource.Metrics; metrics != nil {
+ if metrics.Memory != nil && metrics.Memory.Total != nil {
+ info.MemoryTotal = *metrics.Memory.Total
+ }
+ if metrics.Disk != nil && metrics.Disk.Total != nil {
+ info.DiskTotal = *metrics.Disk.Total
+ }
+ }
+ if px := resource.Proxmox; px != nil {
+ info.Host = px.HostURL
+ info.Instance = px.Instance
+ info.KernelVersion = px.KernelVersion
+ info.PVEVersion = px.PVEVersion
+ info.ClusterName = px.ClusterName
+ info.IsCluster = px.IsClusterMember
+ info.LoadAverage = append([]float64(nil), px.LoadAverage...)
+ if info.Uptime == 0 {
+ info.Uptime = px.Uptime
+ }
+ if px.CPUInfo != nil {
+ info.CPUModel = px.CPUInfo.Model
+ info.CPUCores = px.CPUInfo.Cores
+ info.CPUSockets = px.CPUInfo.Sockets
+ }
+ }
+ if agent := resource.Agent; agent != nil && reportHostAgentID(resource) != "" {
+ info.OSName = agent.OSName
+ info.OSVersion = agent.OSVersion
+ if info.KernelVersion == "" {
+ info.KernelVersion = agent.KernelVersion
+ }
+ if info.CPUCores == 0 {
+ info.CPUCores = agent.CPUCount
+ }
+ if len(info.LoadAverage) == 0 {
+ info.LoadAverage = append([]float64(nil), agent.LoadAverage...)
+ }
+ if info.Uptime == 0 {
+ info.Uptime = agent.UptimeSeconds
+ }
+ if info.MemoryTotal == 0 && agent.Memory != nil {
+ info.MemoryTotal = agent.Memory.Total
+ }
+ }
+ return info
+}
+
+// reportStorageInfo is the report row for a storage pool resource.
+func reportStorageInfo(r unifiedresources.Resource) reporting.StorageInfo {
+ var total, used, available int64
+ var usagePerc float64
+ if r.Metrics != nil && r.Metrics.Disk != nil {
+ if r.Metrics.Disk.Total != nil {
+ total = *r.Metrics.Disk.Total
+ }
+ if r.Metrics.Disk.Used != nil {
+ used = *r.Metrics.Disk.Used
+ }
+ if total > 0 {
+ available = total - used
+ }
+ usagePerc = r.Metrics.Disk.Percent
+ if usagePerc == 0 && total > 0 {
+ usagePerc = (float64(used) / float64(total)) * 100
+ }
+ }
+
+ var storageType, content string
+ if r.Storage != nil {
+ storageType = r.Storage.Type
+ content = r.Storage.Content
+ }
+
+ return reporting.StorageInfo{
+ Name: r.Name,
+ Type: storageType,
+ Status: string(r.Status),
+ Total: total,
+ Used: used,
+ Available: available,
+ UsagePerc: usagePerc,
+ Content: content,
+ }
+}
+
+// reportDiskInfo is the report row for a physical disk resource. Its
+// temperature is the collected reading only (reportDiskTemperature), coloured
+// by the tenant's disk temperature alert thresholds; a nil manager means the
+// factory alert configuration.
+func reportDiskInfo(pd unifiedresources.PhysicalDiskMeta, manager *alerts.Manager) reporting.DiskInfo {
+ temperatureWarning, temperatureCritical := reportDiskTemperatureThresholds(manager, pd.DiskType)
+ return reporting.DiskInfo{
+ Device: pd.DevPath,
+ Model: pd.Model,
+ Serial: pd.Serial,
+ Type: pd.DiskType,
+ Size: pd.SizeBytes,
+ Health: pd.Health,
+ Temperature: reportDiskTemperature(pd),
+ WearLevel: pd.Wearout,
+ TemperatureWarning: temperatureWarning,
+ TemperatureCritical: temperatureCritical,
+ }
+}
diff --git a/internal/api/reporting_subject_alerts_test.go b/internal/api/reporting_subject_alerts_test.go
new file mode 100644
index 0000000000..0cfc51847a
--- /dev/null
+++ b/internal/api/reporting_subject_alerts_test.go
@@ -0,0 +1,98 @@
+package api
+
+import (
+ "context"
+ "testing"
+ "time"
+
+ "github.com/rcourtman/pulse-go-rewrite/internal/models"
+ "github.com/rcourtman/pulse-go-rewrite/internal/unifiedresources"
+ "github.com/rcourtman/pulse-go-rewrite/pkg/reporting"
+)
+
+// Exercise the actual enrichment entry point with both open and resolved
+// alerts. A matching path (including a metrics alias) must not override the
+// journal's recorded-hardware ownership; an earlier path must not hide it.
+func TestReportPhysicalDiskAlertsFollowRecordedHardware(t *testing.T) {
+ const fullWWN = "5000c500a1b2c3d4"
+ type diskSpec struct{ id, node, path, serial, wwn string }
+ base := diskSpec{"physical-disk-subject", "pve1", "/dev/sda", "SER-A", ""}
+ wwnOnly := diskSpec{"physical-disk-subject", "pve1", "/dev/sda", "", "naa." + fullWWN}
+ placeholder := wwnOnly
+ placeholder.serial = "unknown"
+ twin := diskSpec{"physical-disk-other", "pve2", "/dev/sdb", "SER-A", "naa.5000c500000000b2"}
+ for _, tc := range []struct {
+ name string
+ subject diskSpec
+ others []diskSpec
+ node, path, serial, wwn string
+ metricsAlias bool
+ want bool
+ }{
+ {name: "serial", subject: base, node: "pve1", path: "/dev/sda", serial: "ser-a", want: true},
+ {name: "replacement", subject: base, node: "pve1", path: "/dev/sda", serial: "SER-OLD"},
+ {name: "path metrics alias cannot bypass replacement", subject: base, node: "pve1", path: "/dev/sda", serial: "SER-OLD", metricsAlias: true},
+ {name: "earlier path", subject: base, node: "pve1", path: "/dev/sdz", serial: "SER-A", want: true},
+ {name: "earlier node", subject: base, node: "pve2", path: "/dev/sdz", serial: "SER-A", want: true},
+ {name: "WWN only framed", subject: wwnOnly, node: "pve1", path: "/dev/sda", wwn: "wwn-0x" + fullWWN, want: true},
+ {name: "WWN only moved", subject: wwnOnly, node: "pve2", path: "/dev/sdz", wwn: "eui." + fullWWN, want: true},
+ {name: "agent WWN fields", subject: wwnOnly, node: "pve1", path: "/dev/sda", wwn: "5-c50-a1b2c3d4", want: true},
+ {name: "serial to WWN cross source", subject: wwnOnly, node: "pve1", path: "/dev/sda", serial: fullWWN, want: true},
+ {name: "placeholder same WWN", subject: placeholder, node: "pve1", path: "/dev/sda", serial: "UNKNOWN", wwn: "0x" + fullWWN, want: true},
+ {name: "placeholder different WWN", subject: placeholder, node: "pve1", path: "/dev/sda", serial: "UNKNOWN", wwn: "0x5000c500000000b2"},
+ {name: "truncated WWN is not identity", subject: wwnOnly, node: "pve1", path: "/dev/sda", wwn: "0x5000c500a1b2"},
+ {name: "unknown cannot claim identified disk", subject: base, node: "pve1", path: "/dev/sda", serial: "unknown"},
+ {name: "zero cannot claim identified disk", subject: base, node: "pve1", path: "/dev/sda", serial: "00000000"},
+ {name: "shared serial is ambiguous even at path", subject: base, others: []diskSpec{twin}, node: "pve1", path: "/dev/sda", serial: "SER-A"},
+ {name: "WWN decides shared serial", subject: diskSpec{base.id, base.node, base.path, base.serial, "naa." + fullWWN}, others: []diskSpec{twin}, node: "pve2", path: "/dev/sdb", serial: "SER-A", wwn: "0x" + fullWWN, want: true},
+ {name: "WWN decides other twin despite subject path", subject: diskSpec{base.id, base.node, base.path, base.serial, "naa." + fullWWN}, others: []diskSpec{twin}, node: "pve1", path: "/dev/sda", serial: "SER-A", wwn: twin.wwn},
+ {name: "identity less exact path", subject: diskSpec{base.id, base.node, base.path, "unknown", ""}, node: "pve1", path: "/dev/sda", serial: "N/A", want: true},
+ {name: "identity less cannot move by path", subject: diskSpec{base.id, base.node, base.path, "", ""}, node: "pve1", path: "/dev/sdz"},
+ {name: "identity less path ambiguous", subject: diskSpec{base.id, base.node, base.path, "", ""}, others: []diskSpec{{twin.id, base.node, base.path, "", ""}}, node: "pve1", path: "/dev/sda"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ now := time.Date(2026, 10, 7, 12, 0, 0, 0, time.UTC)
+ start := now.Add(-24 * time.Hour)
+ snapshot := reportingEnrichmentSnapshot{}
+ for _, spec := range append([]diskSpec{tc.subject}, tc.others...) {
+ snapshot.Resources = append(snapshot.Resources, unifiedresources.Resource{
+ ID: spec.id, Type: unifiedresources.ResourceTypePhysicalDisk,
+ Proxmox: &unifiedresources.ProxmoxData{Instance: "lab:west", NodeName: spec.node},
+ PhysicalDisk: &unifiedresources.PhysicalDiskMeta{DevPath: spec.path, Serial: spec.serial, WWN: spec.wwn},
+ })
+ }
+ ref := unifiedresources.ProxmoxPhysicalDiskAlertResourceID("lab:west", tc.node, tc.path)
+ identifiers := unifiedresources.ProxmoxPhysicalDiskAlertIdentifiers(ref)
+ alert := models.Alert{ID: identifiers[0], ResourceID: ref, Type: "disk-health", Level: "critical", StartTime: start.Add(time.Hour),
+ Metadata: map[string]any{unifiedresources.MetadataDiskSerial: tc.serial, unifiedresources.MetadataDiskWWN: tc.wwn}}
+ snapshot.ActiveAlerts = []models.Alert{alert}
+ resolved := alert
+ resolved.ID, resolved.Type = identifiers[1], "disk-wearout"
+ snapshot.RecentlyResolved = []models.ResolvedAlert{
+ {Alert: resolved, ResolvedTime: start.Add(time.Hour)},
+ {Alert: resolved, ResolvedTime: start}, // exact boundaries excluded
+ {Alert: resolved, ResolvedTime: now},
+ }
+ // Even a path-shaped alert on the subject's metrics alias is not
+ // a PVE alert unless its canonical alert identifier agrees.
+ unrelated := alert
+ unrelated.ID = "unrelated-alert"
+ snapshot.ActiveAlerts = append(snapshot.ActiveAlerts, unrelated)
+ req := reporting.MetricReportRequest{ResourceType: "disk", ResourceID: tc.subject.id}
+ if tc.metricsAlias {
+ req.MetricsResourceID = ref
+ }
+ NewReportingHandlers(nil, nil).enrichReportRequest(context.Background(), "default", &req, snapshot, start, now)
+ wantCount := 0
+ if tc.want {
+ wantCount = 2
+ }
+ if len(req.Alerts) != wantCount {
+ t.Fatalf("alerts = %+v, want %d owned open/in-window rows", req.Alerts, wantCount)
+ }
+ if tc.want && (req.Alerts[0].ResolvedTime != nil || req.Alerts[1].ResolvedTime == nil || !req.Alerts[1].ResolvedTime.Equal(start.Add(time.Hour))) {
+ t.Fatalf("open/resolved state not preserved: %+v", req.Alerts)
+ }
+ })
+ }
+}
diff --git a/internal/unifiedresources/history_identity_test.go b/internal/unifiedresources/history_identity_test.go
index 03758b80bf..b62fb8dc66 100644
--- a/internal/unifiedresources/history_identity_test.go
+++ b/internal/unifiedresources/history_identity_test.go
@@ -807,7 +807,15 @@ func TestProxmoxDiskAlertOwnerDecisions(t *testing.T) {
ref := ProxmoxPhysicalDiskAlertResourceID("lab", tc.node, tc.device)
got := registry.proxmoxDiskAlertOwner(ref, map[string]any{MetadataDiskSerial: tc.serial, MetadataDiskWWN: tc.wwn})
require.Equal(t, tc.want, got, tc.name)
+ // Reports consume an immutable snapshot, not the live registry. Both
+ // entry points must make the exact same recorded-hardware decision.
+ var snapshot []Resource
+ for _, resource := range registry.resources {
+ snapshot = append(snapshot, *resource)
+ }
+ require.Equal(t, tc.want, ProxmoxPhysicalDiskAlertOwner(ref, map[string]any{MetadataDiskSerial: tc.serial, MetadataDiskWWN: tc.wwn}, snapshot), tc.name)
}
+ require.Empty(t, ProxmoxPhysicalDiskAlertOwner("not-a-PVE-reference", map[string]any{MetadataDiskSerial: "ZA1A2B3C"}, nil))
}
// A read by a PVE disk alert reference reaches the rows owned away from it
diff --git a/internal/unifiedresources/pve_disk_alert_history.go b/internal/unifiedresources/pve_disk_alert_history.go
index e2040b2eaf..bb01ad7764 100644
--- a/internal/unifiedresources/pve_disk_alert_history.go
+++ b/internal/unifiedresources/pve_disk_alert_history.go
@@ -1,6 +1,8 @@
package unifiedresources
import (
+ "iter"
+ "maps"
"strings"
"github.com/rcourtman/pulse-go-rewrite/pkg/diskinventory"
@@ -125,6 +127,31 @@ func (rr *ResourceRegistry) proxmoxDiskAlertOwner(ref string, metadata map[strin
if rr == nil {
return ""
}
+ rr.mu.RLock()
+ defer rr.mu.RUnlock()
+ return proxmoxDiskAlertOwner(ref, metadata, maps.All(rr.resources))
+}
+
+// ProxmoxPhysicalDiskAlertOwner applies the journal's recorded-hardware
+// ownership rule to an immutable unified snapshot. Reports use this same
+// decision, including WWN disambiguation and identity-less path fallback,
+// instead of rebinding a current device path or inventing another matcher.
+// It returns an empty ID for an invalid reference or ambiguous ownership.
+func ProxmoxPhysicalDiskAlertOwner(ref string, metadata map[string]any, resources []Resource) string {
+ if !isProxmoxPhysicalDiskAlertReference(ref) {
+ return ""
+ }
+ return proxmoxDiskAlertOwner(ref, metadata, func(yield func(string, *Resource) bool) {
+ for i := range resources {
+ if !yield(resources[i].ID, &resources[i]) {
+ return
+ }
+ }
+ })
+}
+
+// resources must be repeatable: a second read guards a derived ID collision.
+func proxmoxDiskAlertOwner(ref string, metadata map[string]any, resources iter.Seq2[string, *Resource]) string {
serial, _ := metadata[MetadataDiskSerial].(string)
wwn, _ := metadata[MetadataDiskWWN].(string)
serial, wwn = strings.TrimSpace(serial), strings.TrimSpace(wwn)
@@ -135,10 +162,8 @@ func (rr *ResourceRegistry) proxmoxDiskAlertOwner(ref string, metadata map[strin
machineID = wwn
}
- rr.mu.RLock()
- defer rr.mu.RUnlock()
var matches, sameWWN []string
- for id, resource := range rr.resources {
+ for id, resource := range resources {
if resource == nil || CanonicalResourceType(resource.Type) != ResourceTypePhysicalDisk || resource.PhysicalDisk == nil {
continue
}
@@ -166,8 +191,10 @@ func (rr *ResourceRegistry) proxmoxDiskAlertOwner(ref string, metadata map[strin
return ""
}
derived := MachineIdentityCanonicalID(ResourceTypePhysicalDisk, machineID)
- if rr.resources[derived] != nil {
- return ""
+ for id, resource := range resources {
+ if id == derived && resource != nil {
+ return ""
+ }
}
return derived
}
diff --git a/internal/unifiedresources/registry_test.go b/internal/unifiedresources/registry_test.go
index f18825e856..112ddebfd0 100644
--- a/internal/unifiedresources/registry_test.go
+++ b/internal/unifiedresources/registry_test.go
@@ -13,6 +13,41 @@ import (
"github.com/rcourtman/pulse-go-rewrite/pkg/diskinventory"
)
+// The snapshot entry point shares the registry's journal ownership, without
+// mutating either the snapshot or the alert's recorded metadata.
+func TestProxmoxDiskAlertSnapshotOwnershipMatchesRegistry(t *testing.T) {
+ rr := NewRegistry(nil)
+ rr.resources = map[string]*Resource{
+ "disk-a": {ID: "disk-a", Type: ResourceTypePhysicalDisk,
+ PhysicalDisk: &PhysicalDiskMeta{Serial: "unknown", WWN: "naa.5000c500a1b2c3d4", DevPath: "/dev/sdz"}},
+ "disk-b": {ID: "disk-b", Type: ResourceTypePhysicalDisk,
+ PhysicalDisk: &PhysicalDiskMeta{Serial: "unknown", WWN: "0x5000c500000000b2", DevPath: "/dev/sda"}},
+ }
+ var snapshot []Resource
+ for _, resource := range rr.resources {
+ snapshot = append(snapshot, *resource)
+ }
+ ref := ProxmoxPhysicalDiskAlertResourceID("lab", "pve1", "/dev/sda")
+ for _, tc := range []struct{ name, serial, wwn, want string }{
+ {"moved hardware without PVE facet", "unknown", "wwn-0x5000c500a1b2c3d4", "disk-a"},
+ {"placeholder is not hardware", "unknown", "", ""},
+ {"second hardware", "unknown", "5000c500000000b2", "disk-b"},
+ {"derived absent hardware", "NEW00001", "", MachineIdentityCanonicalID(ResourceTypePhysicalDisk, "NEW00001")},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ metadata := map[string]any{MetadataDiskSerial: tc.serial, MetadataDiskWWN: tc.wwn}
+ before, _ := json.Marshal(snapshot)
+ if got := ProxmoxPhysicalDiskAlertOwner(ref, metadata, snapshot); got != tc.want || got != rr.proxmoxDiskAlertOwner(ref, metadata) {
+ t.Fatalf("snapshot owner = %q, registry = %q, want %q", got, rr.proxmoxDiskAlertOwner(ref, metadata), tc.want)
+ }
+ after, _ := json.Marshal(snapshot)
+ if string(before) != string(after) || metadata[MetadataDiskSerial] != tc.serial || metadata[MetadataDiskWWN] != tc.wwn {
+ t.Fatal("ownership read mutated snapshot or recorded identity")
+ }
+ })
+ }
+}
+
func TestProxmoxGuestReadAdmissionReplacesPreviousFacet(t *testing.T) {
rr := NewRegistry(nil)
vm := models.VM{ID: "pve:node:105", Instance: "pve", Node: "node", VMID: 105, Type: "qemu", Status: "running", Name: "guest", LastSeen: time.Now(), Disk: models.Disk{Total: 100, Used: 30, Usage: 30}}
diff --git a/scripts/repo-boundary-paid-surface.allowlist b/scripts/repo-boundary-paid-surface.allowlist
index 6b8d35f0cd..513c2e1afd 100644
--- a/scripts/repo-boundary-paid-surface.allowlist
+++ b/scripts/repo-boundary-paid-surface.allowlist
@@ -5,6 +5,9 @@ internal/api/licensing_bridge.go
internal/api/licensing_handlers.go
internal/api/magic_link.go
internal/api/reporting_runtime_snapshot.go
+# Shared subject enrichment behind the existing reporting admin binder/gates;
+# not a new paid endpoint or entitlement implementation. Exact path only.
+internal/api/reporting_subject_alerts.go
internal/api/router.go
internal/api/router_routes_auth_security.go
internal/api/router_routes_cloud.go
diff --git a/scripts/repo-boundary-regression.py b/scripts/repo-boundary-regression.py
new file mode 100644
index 0000000000..1ac719179a
--- /dev/null
+++ b/scripts/repo-boundary-regression.py
@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Run the real paid-boundary audit against isolated source fixtures."""
+
+from pathlib import Path
+import shutil
+import subprocess
+import tempfile
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SUBJECT = "reporting_subject_alerts.go"
+
+
+class ReportingSubjectBoundaryTests(unittest.TestCase):
+ def test_shared_exemption_is_exact_and_preserves_import_boundaries(self):
+ variants = [
+ ("shared pipeline", None, None, None),
+ (
+ "new reporting implementation", "reporting_subject_alerts_extra.go",
+ "package api\n", "new production paid-domain implementation files are not baselined",
+ ),
+ (
+ "exact path not prefix", "reporting_subject_alerts.go.extra.go",
+ "package api\n", "new production paid-domain implementation files are not baselined",
+ ),
+ (
+ "private root import", SUBJECT,
+ 'package api\nimport _ "github.com/rcourtman/pulse-go-rewrite/internal/license"\n',
+ "API root imports of internal/license remain",
+ ),
+ (
+ "licensing bridge required", SUBJECT,
+ 'package api\nimport _ "github.com/rcourtman/pulse-go-rewrite/pkg/licensing"\n',
+ "API files outside bridge allowlist still import pkg/licensing",
+ ),
+ ]
+ for name, filename, content, rejection in variants:
+ with self.subTest(name=name), tempfile.TemporaryDirectory() as temporary:
+ fixture = Path(temporary)
+ for directory in ("internal/api", "internal/license"):
+ for source in (ROOT / directory).rglob("*.go"):
+ if source.name.endswith("_test.go"):
+ continue
+ target = fixture / source.relative_to(ROOT)
+ target.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copyfile(source, target)
+ for filename_to_copy in (
+ "scripts/audit-private-boundary.sh",
+ "scripts/repo-boundary-paid-surface.allowlist",
+ "scripts/repo-boundary-private-implementation.baseline",
+ ):
+ target = fixture / filename_to_copy
+ target.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copyfile(ROOT / filename_to_copy, target)
+ if filename:
+ (fixture / "internal/api" / filename).write_text(content)
+ result = subprocess.run(
+ ["bash", "scripts/audit-private-boundary.sh", "--enforce"],
+ cwd=fixture, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+ text=True, timeout=30, check=False,
+ )
+ self.assertEqual(result.returncode, 1 if rejection else 0, result.stdout)
+ if rejection:
+ self.assertIn(rejection, result.stdout)
+ self.assertIn(filename, result.stdout)
+
+
+if __name__ == "__main__":
+ unittest.main()