pulse/pkg/reporting/reporting.go

package reporting

import (
	"time"
)

// ReportFormat represents the output format of a report
type ReportFormat string

const (
	FormatCSV ReportFormat = "csv"
	FormatPDF ReportFormat = "pdf"
)

// MetricReportRequest defines the parameters for generating a report
type MetricReportRequest struct {
	ResourceType string
	ResourceID   string
	MetricType   string // Optional, if empty all metrics for the resource are included
	Start        time.Time
	End          time.Time
	Format       ReportFormat
	Title        string
	Branding     ReportBranding

	// OrgID is the organization the report is generated for. An engine that
	// resolves metrics per organization reads only this organization's
	// metrics store and refuses a request that leaves it empty.
	OrgID string

	// MetricsResourceID overrides ResourceID for metrics-store queries.
	// The v6 API addresses resources by canonical unified ID while the
	// metrics store is keyed by each platform's native source ID (the
	// resource's metricsTarget); recovery points and Patrol findings stay
	// keyed by the unified ID. Handlers set this from the resource's
	// metricsTarget so the store query can match without changing the
	// identity the rest of the report pipeline sees.
	MetricsResourceID string

	// Optional enrichment data (populated by handler from monitor state)
	Resource     *ResourceInfo     // Details about the resource being reported on
	Alerts       []AlertInfo       // Active and recently resolved alerts for this resource
	Backups      []BackupInfo      // Backup information for VMs/containers
	Storage      []StorageInfo     // Storage pools (for nodes)
	Disks        []DiskInfo        // Physical disk health (for nodes)
	Availability *AvailabilityInfo // Observed availability over the window (from the state timeline)

	// Optional narrative interpretation. When Narrator is non-nil the
	// engine builds a NarrativeInput from the queried report data and asks
	// it to produce the executive summary; on error or nil it falls back to
	// the heuristic narrator. Findings are passed through to NarrativeInput
	// so a narrator can reference Patrol activity in the period.
	Narrator         Narrator
	FindingsProvider FindingsProvider
}

// AvailabilityInfo summarizes a resource's observed availability over the
// report window, derived from the recorded resource state timeline.
//
// Time the resource was absent from the registry or in an unknown state
// (for example while the monitor itself was restarting) is treated as
// unobserved: it is excluded from the uptime calculation entirely rather
// than counted as downtime, and disclosed through ObservedPercent. A
// monitoring gap is not an outage, and a client-facing stability report
// must not present one as such.
type AvailabilityInfo struct {
	// UptimePercent is up / (up + down) over the observed portion of the
	// window. Online and warning states count as up; offline counts as
	// down. Zero when the resource was never observed in the window.
	UptimePercent float64
	// ObservedPercent is the share of the report window during which the
	// resource state was actually being recorded.
	ObservedPercent float64
	// TotalDowntime is the cumulative time spent in a down state.
	TotalDowntime time.Duration
	// LongestOutage is the longest contiguous stretch of down time.
	LongestOutage time.Duration
	// DownIncidents counts distinct transitions into a down state.
	DownIncidents int
}

// Observed reports whether the resource was observed at all in the window.
func (a *AvailabilityInfo) Observed() bool {
	return a != nil && a.ObservedPercent > 0
}

// ResourceInfo contains details about the resource being reported on
type ResourceInfo struct {
	Name          string
	DisplayName   string
	Status        string
	Host          string // URL for nodes
	Node          string // Parent node for VMs/containers
	Instance      string // Proxmox instance name
	Uptime        int64
	KernelVersion string
	PVEVersion    string
	OSName        string
	OSVersion     string
	IPAddresses   []string
	CPUModel      string
	CPUCores      int
	CPUSockets    int
	MemoryTotal   int64
	DiskTotal     int64
	LoadAverage   []float64
	Temperature   *float64 // CPU temp if available
	Tags          []string
	ClusterName   string
	IsCluster     bool
}

// AlertInfo contains alert information for the report
type AlertInfo struct {
	Type         string
	Level        string // warning, critical
	Message      string
	Value        float64
	Threshold    float64
	StartTime    time.Time
	ResolvedTime *time.Time // nil if still active
	Acknowledged bool
	// ResourceID is the resource the alert was raised on, so an alert that
	// moved can find the alert its successor raised for the same metric.
	ResourceID string
	// Resolution is set only on a resolved alert whose close was not a
	// recovery, such as a node alert handed to its Pulse agent. A report
	// never counts such an alert as resolved.
	Resolution *AlertResolution
}

// AlertResolution says why an alert closed without its condition clearing.
// It mirrors models.AlertResolution so this package stays free of internal
// dependencies.
type AlertResolution struct {
	// Reason is the alert engine's reason code, such as
	// AlertResolutionMovedToAgent.
	Reason              string
	SuccessorResourceID string
	SuccessorName       string
	// Summary is the alert engine's one-line account, such as "Alert moved
	// to pve1 (Host Agent). This is not a recovery: check the agent for the
	// current reading."
	Summary string
}

// BackupInfo contains backup information for VMs/containers
type BackupInfo struct {
	Type       string // vzdump, pbs
	Storage    string
	Timestamp  time.Time
	Size       int64
	Verified   bool
	Protected  bool
	VolID      string
	NextBackup *time.Time
}

// StorageInfo contains storage pool information
type StorageInfo struct {
	Name      string
	Type      string // lvm, zfs, dir, nfs, etc.
	Status    string
	Total     int64
	Used      int64
	Available int64
	UsagePerc float64
	Content   string // images, rootdir, backup, etc.
	ZFSHealth string // For ZFS pools
	ZFSErrors int    // Checksum/read/write errors
}

// DiskInfo contains physical disk health information
type DiskInfo struct {
	Device      string
	Model       string
	Serial      string
	Type        string // nvme, ssd, hdd
	Size        int64
	Health      string // PASSED, FAILED, UNKNOWN
	Temperature int    // Celsius
	WearLevel   int    // 0-100, percentage of life REMAINING (100 = healthy, 0 = end of life, -1 = unknown)
	// TemperatureWarning and TemperatureCritical are the disk's alert disk
	// temperature thresholds in Celsius (the clear value and the trigger). The
	// reading is amber from Warning and red from Critical, as in the Physical
	// Disks Temp column. A zero Critical leaves the reading uncoloured.
	TemperatureWarning  float64
	TemperatureCritical float64
}

// MultiReportRequest defines the parameters for generating a multi-resource report.
type MultiReportRequest struct {
	Resources  []MetricReportRequest // One per resource, each with enrichment
	Format     ReportFormat
	Start      time.Time
	End        time.Time
	Title      string
	MetricType string
	Branding   ReportBranding

	// OrgID is the organization the report is generated for. It applies to
	// every resource in Resources, overriding any OrgID they carry.
	OrgID string

	// Optional fleet-level narrative interpretation. When FleetNarrator is
	// non-nil the engine builds a FleetNarrativeInput from the queried
	// per-resource report data and asks it to produce the cross-resource
	// summary; on error or nil it falls back to the heuristic fleet
	// narrator. FindingsProvider, when set, is consulted per-resource so
	// patrol findings can flow into per-resource narratives.
	FleetNarrator    FleetNarrator
	Narrator         Narrator
	FindingsProvider FindingsProvider
}

// MultiReportData holds the data for multi-resource report generation.
type MultiReportData struct {
	Title       string
	Start       time.Time
	End         time.Time
	GeneratedAt time.Time
	Resources   []*ReportData // Reuse existing ReportData per resource
	TotalPoints int
	Brand       *ReportBrand

	// Fleet-level narrative interpretation, populated by the engine when
	// the request supplies a FleetNarrator (or always populated with the
	// heuristic fallback). The renderer prefers this over recomputing
	// observations inline.
	FleetNarrative *FleetNarrative
}

// Engine defines the interface for report generation.
// This allows the enterprise version to provide PDF/CSV generation.
//
// NarrativeFor and FleetNarrativeFor return the structured narrative
// without rendering, for callers that want the synthesis layer in a
// non-PDF form (Pulse Assistant tool calls, programmatic consumers).
type Engine interface {
	Generate(req MetricReportRequest) (data []byte, contentType string, err error)
	GenerateMulti(req MultiReportRequest) (data []byte, contentType string, err error)
	NarrativeFor(req MetricReportRequest) (*Narrative, error)
	FleetNarrativeFor(req MultiReportRequest) (*FleetNarrative, error)
}

var (
	globalEngine Engine
)

// SetEngine sets the global report engine.
func SetEngine(e Engine) {
	globalEngine = e
}

// GetEngine returns the current global report engine.
func GetEngine() Engine {
	return globalEngine
}