diff --git a/agent/api/server.go b/agent/api/server.go index 1165deaf..d127c052 100644 --- a/agent/api/server.go +++ b/agent/api/server.go @@ -542,6 +542,15 @@ func (s *Server) routeVMs(w http.ResponseWriter, r *http.Request, segments []str } switch segments[3] { + case "backup-readiness": + if len(segments) == 4 && r.Method == http.MethodGet { + if !requireManage(w, actor) { + return + } + result, err := s.Hypervisor.GetBackupReadiness(r.Context(), uuid) + writeResult(w, result, err) + return + } case "backups": if len(segments) == 4 && r.Method == http.MethodPost { if !requireManage(w, actor) { diff --git a/agent/api/server_test.go b/agent/api/server_test.go index f08ed103..9f68088d 100644 --- a/agent/api/server_test.go +++ b/agent/api/server_test.go @@ -40,6 +40,8 @@ type testHypervisor struct { cleanupBackupLast hypervisor.CleanupBackupWorkspaceRequest inspectionResult *hypervisor.OperationInspection inspectionErr error + backupReadiness hypervisor.BackupReadiness + backupReadinessErr error } type apiFailure struct { @@ -63,6 +65,10 @@ func (h *testHypervisor) ListVMs(context.Context) ([]hypervisor.VMMetadata, erro return []hypervisor.VMMetadata{}, nil } +func (h *testHypervisor) GetBackupReadiness(context.Context, string) (hypervisor.BackupReadiness, error) { + return h.backupReadiness, h.backupReadinessErr +} + func (h *testHypervisor) ConfigureStorage(context.Context, hypervisor.StorageConfigurationRequest) (hypervisor.StorageConfigurationResult, error) { h.mu.Lock() h.configureCalls++ @@ -228,6 +234,41 @@ func TestLegacyDailyTrafficRouteIsRemoved(t *testing.T) { } } +func TestBackupReadinessIsBoundedReadOnlyEvidence(t *testing.T) { + api := newTestAPI(t) + api.hv.backupReadiness = hypervisor.BackupReadiness{ + Eligible: false, Retryable: true, Reason: "backup_rescue_active", + } + const uuid = "123e4567-e89b-42d3-a456-426614174000" + response := api.request(t, http.MethodGet, + "/v1/vms/"+uuid+"/backup-readiness", nil, + auth.Actor{UserID: 1, CanManage: true}) + if response.Code != http.StatusOK { + t.Fatalf("backup readiness status=%d body=%s", + response.Code, response.Body.String()) + } + var readiness hypervisor.BackupReadiness + if err := json.Unmarshal(response.Body.Bytes(), &readiness); err != nil { + t.Fatal(err) + } + if readiness != api.hv.backupReadiness { + t.Fatalf("backup readiness=%#v want=%#v", + readiness, api.hv.backupReadiness) + } +} + +func TestBackupReadinessRequiresManageCapability(t *testing.T) { + api := newTestAPI(t) + const uuid = "123e4567-e89b-42d3-a456-426614174000" + response := api.request(t, http.MethodGet, + "/v1/vms/"+uuid+"/backup-readiness", nil, + auth.Actor{UserID: 1}) + if response.Code != http.StatusForbidden { + t.Fatalf("backup readiness without manage=%d body=%s", + response.Code, response.Body.String()) + } +} + func requireOperationResponseIdentity(t *testing.T, response *httptest.ResponseRecorder, operationID, action, resourceID, requestFingerprint string) operationResponse { t.Helper() diff --git a/agent/hypervisor/libvirt_backup.go b/agent/hypervisor/libvirt_backup.go index 8d72387b..d532f326 100644 --- a/agent/hypervisor/libvirt_backup.go +++ b/agent/hypervisor/libvirt_backup.go @@ -25,6 +25,34 @@ func (l *Libvirt) CreateBackup(ctx context.Context, uuid string, request BackupR return l.createPortableBackup(ctx, uuid, request) } +// GetBackupReadiness reports only transient blockers which automatic backup +// may safely defer. It deliberately does not reserve resources or consume +// retained job evidence, and CreateBackup repeats these checks before mutation. +func (l *Libvirt) GetBackupReadiness(ctx context.Context, uuid string) (BackupReadiness, error) { + domain, err := l.domainByUUID(ctx, uuid) + if err != nil { + return BackupReadiness{}, err + } + defer domain.Free() + _, metadata, err := requireManagedDomain(domain) + if err != nil { + return BackupReadiness{}, err + } + if reason := backupTransientBlocker(metadata); reason != "" { + return BackupReadiness{Eligible: false, Retryable: true, Reason: reason}, nil + } + if err := ensureNoActiveDomainJobIfRunning(domain); err != nil { + var public interface{ PublicCode() string } + if errors.As(err, &public) && public.PublicCode() == "domain_job_active" { + return BackupReadiness{ + Eligible: false, Retryable: true, Reason: "domain_job_active", + }, nil + } + return BackupReadiness{}, err + } + return BackupReadiness{Eligible: true, Retryable: false}, nil +} + func (l *Libvirt) createPortableBackup(ctx context.Context, uuid string, request BackupRequest) (_ BackupResult, resultErr error) { client := objecttransfer.New() defer client.CloseIdleConnections() @@ -275,10 +303,7 @@ func (l *Libvirt) validateBackupSource(ctx context.Context, uuid, backupKey stri } defer pool.Free() defer volume.Free() - if metadata.RescueTemplateID != "" { - return false, PortableRestoreContract{}, NewError(ErrConflict, "backup_rescue_active", "VM backup is unavailable while rescue media is attached", nil) - } - if err := validateBackupTransitionState(metadata); err != nil { + if err := validateBackupTransientState(metadata); err != nil { return false, PortableRestoreContract{}, err } for _, stored := range metadata.Snapshots { @@ -404,17 +429,34 @@ func portableQ35Machine(machine string) bool { return machine == "q35" || strings.HasPrefix(machine, "pc-q35-") } -func validateBackupTransitionState(metadata *domainMetadataXML) error { +func backupTransientBlocker(metadata *domainMetadataXML) string { + if metadata != nil && metadata.RescueTemplateID != "" { + return "backup_rescue_active" + } // Reinstall and snapshot restore deliberately retain their transition kind // and operation ID after the old root has been deleted. Those markers prove // a completed root switch during reconciliation; only a pending old root // means that the disk transition is still active. if metadata != nil && metadata.PendingCleanupVolume != "" { + return "backup_disk_transition_active" + } + return "" +} + +func validateBackupTransientState(metadata *domainMetadataXML) error { + switch backupTransientBlocker(metadata) { + case "backup_rescue_active": + return NewError(ErrConflict, "backup_rescue_active", "VM backup is unavailable while rescue media is attached", nil) + case "backup_disk_transition_active": return NewError(ErrConflict, "backup_disk_transition_active", "VM backup is unavailable during a disk transition", nil) } return nil } +func validateBackupTransitionState(metadata *domainMetadataXML) error { + return validateBackupTransientState(metadata) +} + func validateSingleWritableRoot(definition *libvirtxml.Domain) error { if definition == nil || definition.Devices == nil { return NewError(ErrConflict, "backup_disk_layout_unsupported", "VM disk layout is unavailable for portable backup", nil) diff --git a/agent/hypervisor/libvirt_backup_test.go b/agent/hypervisor/libvirt_backup_test.go index 1603a488..48803a81 100644 --- a/agent/hypervisor/libvirt_backup_test.go +++ b/agent/hypervisor/libvirt_backup_test.go @@ -13,6 +13,32 @@ import ( "libvirt.org/go/libvirtxml" ) +func TestBackupTransientBlockerUsesOneAuthoritativeMapping(t *testing.T) { + tests := []struct { + name string + metadata *domainMetadataXML + reason string + }{ + {name: "ready", metadata: &domainMetadataXML{}}, + {name: "rescue", metadata: &domainMetadataXML{RescueTemplateID: "rescue-image"}, reason: "backup_rescue_active"}, + {name: "cleanup", metadata: &domainMetadataXML{PendingCleanupVolume: "root-old.qcow2"}, reason: "backup_disk_transition_active"}, + } + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + if got := backupTransientBlocker(test.metadata); got != test.reason { + t.Fatalf("blocker=%q want=%q", got, test.reason) + } + err := validateBackupTransientState(test.metadata) + if test.reason == "" && err != nil { + t.Fatalf("ready state rejected: %v", err) + } + if test.reason != "" && errorPublicCode(err) != test.reason { + t.Fatalf("validation code=%q want=%q", errorPublicCode(err), test.reason) + } + }) + } +} + func portableRestoreDomainFixture(t *testing.T) (*Libvirt, *libvirtxml.Domain, *domainMetadataXML) { t.Helper() definition := validDomainDefinition() diff --git a/agent/hypervisor/libvirt_connection.go b/agent/hypervisor/libvirt_connection.go index 2710d457..3ee13807 100644 --- a/agent/hypervisor/libvirt_connection.go +++ b/agent/hypervisor/libvirt_connection.go @@ -624,6 +624,12 @@ func (m *managedLibvirt) GetVMMetadata(ctx context.Context, uuid string) (VMMeta return managedCall(m, ctx, false, func(h Hypervisor) (VMMetadata, error) { return h.GetVMMetadata(ctx, uuid) }) } +func (m *managedLibvirt) GetBackupReadiness(ctx context.Context, uuid string) (BackupReadiness, error) { + return managedCall(m, ctx, false, func(h Hypervisor) (BackupReadiness, error) { + return h.GetBackupReadiness(ctx, uuid) + }) +} + func (m *managedLibvirt) CreateVM(ctx context.Context, request CreateVMRequest) (VMMetadata, error) { return managedCall(m, ctx, true, func(h Hypervisor) (VMMetadata, error) { return h.CreateVM(ctx, request) }) } diff --git a/agent/hypervisor/types.go b/agent/hypervisor/types.go index 289efdbf..feeca794 100644 --- a/agent/hypervisor/types.go +++ b/agent/hypervisor/types.go @@ -192,6 +192,15 @@ type VMState struct { EffectConfirmed bool `json:"effect_confirmed,omitempty"` } +// BackupReadiness is bounded, read-only evidence that a VM may enter the +// portable-backup workflow. It is advisory: CreateBackup must re-check the +// same transient blockers immediately before any mutation. +type BackupReadiness struct { + Eligible bool `json:"eligible"` + Retryable bool `json:"retryable"` + Reason string `json:"reason,omitempty"` +} + type Disk struct { // Path is agent-local implementation data. It must never cross the API or // be persisted in an operation result. @@ -977,6 +986,7 @@ type Hypervisor interface { ListVMs(context.Context) ([]VMMetadata, error) GetVMState(context.Context, string) (VMState, error) GetVMMetadata(context.Context, string) (VMMetadata, error) + GetBackupReadiness(context.Context, string) (BackupReadiness, error) CreateVM(context.Context, CreateVMRequest) (VMMetadata, error) CreateBackup(context.Context, string, BackupRequest) (BackupResult, error) CleanupBackupWorkspace(context.Context, string, CleanupBackupWorkspaceRequest) (CleanupBackupWorkspaceResult, error) @@ -1060,6 +1070,9 @@ func (Unsupported) GetVMState(context.Context, string) (VMState, error) { func (Unsupported) GetVMMetadata(context.Context, string) (VMMetadata, error) { return VMMetadata{}, unsupported("VM metadata") } +func (Unsupported) GetBackupReadiness(context.Context, string) (BackupReadiness, error) { + return BackupReadiness{}, unsupported("VM backup readiness") +} func (Unsupported) CreateVM(context.Context, CreateVMRequest) (VMMetadata, error) { return VMMetadata{}, unsupported("VM create") }