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.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
package model
import (
"time"
"github.com/rcourtman/pulse-go-rewrite/internal/operationaltrust"
)
// Provider identifies the system that produced a recovery point.
// This is intentionally a string (not an enum) to keep forward-compatibility with new platforms.
type Provider string
const (
ProviderProxmoxPVE Provider = "proxmox-pve"
ProviderProxmoxPBS Provider = "proxmox-pbs"
ProviderProxmoxPMG Provider = "proxmox-pmg"
ProviderKubernetes Provider = "kubernetes"
ProviderTrueNAS Provider = "truenas"
ProviderDocker Provider = "docker"
ProviderAgent Provider = "agent"
ProviderHostAgent Provider = ProviderAgent
)
type Kind string
const (
KindSnapshot Kind = "snapshot"
KindBackup Kind = "backup"
KindOther Kind = "other"
)
type Mode string
const (
ModeSnapshot Mode = "snapshot"
ModeLocal Mode = "local"
ModeRemote Mode = "remote"
)
type Outcome string
const (
OutcomeSuccess Outcome = "success"
OutcomeWarning Outcome = "warning"
OutcomeFailed Outcome = "failed"
OutcomeRunning Outcome = "running"
OutcomeUnknown Outcome = "unknown"
)
// ExternalRef is used when a recovery point cannot be linked to a unified resource.
// Example: a Kubernetes PVC or a TrueNAS dataset.
type ExternalRef struct {
Type string `json:"type"`
Namespace string `json:"namespace,omitempty"`
Name string `json:"name,omitempty"`
UID string `json:"uid,omitempty"`
ID string `json:"id,omitempty"`
Class string `json:"class,omitempty"`
Extra map[string]string `json:"extra,omitempty"`
}
// RecoveryPoint represents a single restore point (snapshot or backup artifact).
//
// IMPORTANT: Recovery points are NOT modeled as unifiedresources.Resource. They are high-cardinality
// time-based artifacts and are persisted separately with retention.
type RecoveryPoint struct {
ID string `json:"id"`
Provider Provider `json:"provider"`
Kind Kind `json:"kind"`
Mode Mode `json:"mode"`
Outcome Outcome `json:"outcome"`
StartedAt *time.Time `json:"startedAt,omitempty"`
CompletedAt *time.Time `json:"completedAt,omitempty"`
SizeBytes *int64 `json:"sizeBytes,omitempty"`
Verified *bool `json:"verified,omitempty"`
Encrypted *bool `json:"encrypted,omitempty"`
Immutable *bool `json:"immutable,omitempty"`
// Link to a unified resource when possible.
SubjectResourceID string `json:"subjectResourceId,omitempty"`
RepositoryResourceID string `json:"repositoryResourceId,omitempty"`
SubjectRef *ExternalRef `json:"subjectRef,omitempty"`
RepositoryRef *ExternalRef `json:"repositoryRef,omitempty"`
// Provider-specific details for drill-down (kept small).
Details map[string]any `json:"details,omitempty"`
// ProviderScope is the stable provider-local collection scope used to
// correlate this point with provider history and permission observations.
ProviderScope string `json:"providerScope,omitempty"`
// Evidence carries the typed provenance for this recovery point. Older
// persisted rows may omit it and are treated as unknown-quality evidence.
Evidence *operationaltrust.EvidenceEnvelope `json:"evidence,omitempty"`
// Display contains normalized, provider-agnostic fields intended for UIs.
// These fields are derived at ingest time and/or backfilled in the store.
Display *RecoveryPointDisplay `json:"display,omitempty"`
}
// RecoveryPointDisplay is a normalized, UI-friendly view of a recovery point.
// These fields are safe to depend on across platforms and avoid UIs needing provider-specific heuristics.
type RecoveryPointDisplay struct {
SubjectLabel string `json:"subjectLabel,omitempty"`
SubjectType string `json:"subjectType,omitempty"`
ItemType string `json:"itemType,omitempty"`
IsWorkload bool `json:"isWorkload,omitempty"`
ClusterLabel string `json:"clusterLabel,omitempty"`
NodeHostLabel string `json:"nodeHostLabel,omitempty"`
NamespaceLabel string `json:"namespaceLabel,omitempty"`
EntityIDLabel string `json:"entityIdLabel,omitempty"`
RepositoryLabel string `json:"repositoryLabel,omitempty"`
DetailsSummary string `json:"detailsSummary,omitempty"`
}
// VerifyIntent is a tri-state summary of whether a rollup's most recent
// successful backup has been verified within the configured staleness window.
type VerifyIntent string
const (
// VerifyIntentVerified means a verification-bearing successful recovery
// point exists at or before evaluation time within the staleness window.
VerifyIntentVerified VerifyIntent = "verified"
// VerifyIntentStale means a successful backup exists for the subject but
// no verification-bearing point has landed within the staleness window.
VerifyIntentStale VerifyIntent = "stale"
// VerifyIntentUnknown means there is no successful backup, or a reported
// success/verification date is in the future and its age cannot be assessed.
VerifyIntentUnknown VerifyIntent = "unknown"
)
// ProtectionRollup is a per-resource summary derived from recovery points.
type ProtectionRollup struct {
// RollupID is a stable identifier used for drill-down into points.
// It corresponds to the internal subject key:
// - linked resources: "res:<resource-id>"
// - external refs: "ext:<hash>"
RollupID string `json:"rollupId"`
// Latest known subject identity for display in UIs.
SubjectResourceID string `json:"subjectResourceId,omitempty"`
SubjectRef *ExternalRef `json:"subjectRef,omitempty"`
// Display mirrors the latest normalized subject-facing labels derived from
// the newest point in the rollup so protected-inventory UIs can prefer the
// canonical label contract before falling back to opaque ids.
Display *RecoveryPointDisplay `json:"display,omitempty"`
LastAttemptAt *time.Time `json:"lastAttemptAt,omitempty"`
LastSuccessAt *time.Time `json:"lastSuccessAt,omitempty"`
LastOutcome Outcome `json:"lastOutcome"`
// Providers that contributed points within the query window.
Providers []Provider `json:"providers,omitempty"`
// VerifyIntent summarises whether the most recent successful backup for
// this subject has been verified within the staleness window. Emitted
// omitempty so existing rollup payload snapshots stay stable for callers
// that have not opted into the read-side verify loop.
VerifyIntent VerifyIntent `json:"verifyIntent,omitempty"`
// LastVerifiedAt is the completion timestamp of the newest
// verification-bearing recovery point on the rollup window. Nil when no
// verified point exists in the window.
LastVerifiedAt *time.Time `json:"lastVerifiedAt,omitempty"`
}
type ListPointsOptions struct {
Provider Provider
Kind Kind
Mode Mode
Outcome Outcome
SubjectResourceID string
// RollupID filters by the stable subject key ("res:<id>" or "ext:<hash>").
// When set, it takes precedence over SubjectResourceID.
RollupID string
From *time.Time
To *time.Time
// Query is a best-effort free-text filter over normalized fields.
Query string
// ItemType filters points to the canonical recovery item classification.
ItemType string
// Normalized filters derived from the recovery point index.
ClusterLabel string
NodeHostLabel string
NamespaceLabel string
// WorkloadOnly filters points to those whose subject is considered a workload.
WorkloadOnly bool
// Verification filters by tri-state verification fields ("verified", "unverified", "unknown").
Verification string
Page int
Limit int
}
// List pagination bounds shared by every recovery list serving path. The API
// handlers (internal/api/recovery_handlers.go) and the persistent store
// (internal/recovery/store) must clamp ListPointsOptions.Limit to these same
// bounds, because the handlers echo pagination meta (limit, totalPages)
// computed from them and clients walk the reported page count.
const (
DefaultListPageLimit = 100
MaxListPageLimit = 500
)
// PointsSeriesBucket is a per-day aggregation of recovery points within a time window.
// Day is formatted as YYYY-MM-DD in the requested (client) timezone.
type PointsSeriesBucket struct {
Day string `json:"day"`
Total int `json:"total"`
Snapshot int `json:"snapshot"`
Local int `json:"local"`
Remote int `json:"remote"`
}
// PointsFacets provides distinct filter values for recovery points within a time window.
type PointsFacets struct {
Clusters []string `json:"clusters,omitempty"`
NodesHosts []string `json:"nodesHosts,omitempty"`
Namespaces []string `json:"namespaces,omitempty"`
ItemTypes []string `json:"itemTypes,omitempty"`
HasSize bool `json:"hasSize,omitempty"`
HasVerification bool `json:"hasVerification,omitempty"`
HasEntityID bool `json:"hasEntityId,omitempty"`
}