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.

8.6 KB
Raw Blame
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"`
}