kvm: harden NVRAM freeze status parsing and document UEFI snapshot suspend

Address Copilot's review comment on #13020. `JsonParser.parse(...)`,
`.get("return")` and `.getAsString()` in `verifyVmFilesystemsFrozen` can
throw unchecked exceptions (`JsonSyntaxException`, `IllegalStateException`,
`NullPointerException`) on malformed or unexpected QEMU guest-agent
responses, bypassing the surrounding `catch (LibvirtException | IOException)`
and potentially leaving the guest frozen until the `finally` recovery
runs. Parse defensively, validate that `return` is a JSON string, and
explicitly treat `{"error": {...}}` guest-agent responses as an IO
failure so the outer handler thaws/resumes the guest and surfaces a
proper failure answer.

Also document in PendingReleaseNotes that taking a disk-only instance
snapshot for KVM UEFI VMs now briefly suspends the guest while the
NVRAM sidecar is copied. Non-UEFI VMs are unaffected.

Add regression tests covering the guest-agent error response and the
malformed-JSON path, including verification that the thaw recovery is
invoked when freeze verification fails.

Signed-off-by: kunal.behbudzade <kunal.behbudzade@btsgrp.com>

Author: kunal.behbudzade

PendingReleaseNotes

@@ -48,3 +48,8 @@ example.ver.1 > example.ver.2:
   * UEFI disk-only instance snapshots taken before this change do not contain an
     NVRAM sidecar and cannot be safely reverted. Take a new snapshot after
     upgrading before relying on revert for UEFI VMs.
+
+  * Taking a disk-only instance snapshot for KVM UEFI VMs now briefly suspends
+    the guest while the NVRAM sidecar is copied, so that the captured firmware
+    state is consistent with the disk snapshot. Non-UEFI VMs are unaffected and
+    continue to snapshot live.

plugins/hypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/wrapper/LibvirtCreateDiskOnlyVMSnapshotCommandWrapper.java

@@ -41,6 +41,8 @@
 import org.libvirt.Connect;
 import org.libvirt.Domain;
 import org.libvirt.LibvirtException;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
 import com.google.gson.JsonParser;
 
 import java.io.File;
@@ -315,11 +317,31 @@ protected void freezeVmFilesystems(Domain domain, String vmName) throws LibvirtE
 
     protected void verifyVmFilesystemsFrozen(Domain domain, String vmName) throws LibvirtException, IOException {
         String status = getResultOfQemuCommand(FreezeThawVMCommand.STATUS, domain);
-        if (StringUtils.isBlank(status) || !new JsonParser().parse(status).isJsonObject()) {
+        if (StringUtils.isBlank(status)) {
             throw new IOException(String.format("Failed to verify VM [%s] filesystem freeze state before taking the disk-only VM snapshot. Result: %s", vmName, status));
         }
 
-        String statusResult = new JsonParser().parse(status).getAsJsonObject().get("return").getAsString();
+        JsonObject statusObject;
+        try {
+            JsonElement statusElement = new JsonParser().parse(status);
+            if (!statusElement.isJsonObject()) {
+                throw new IOException(String.format("Failed to verify VM [%s] filesystem freeze state before taking the disk-only VM snapshot. Result: %s", vmName, status));
+            }
+            statusObject = statusElement.getAsJsonObject();
+        } catch (RuntimeException e) {
+            throw new IOException(String.format("Failed to verify VM [%s] filesystem freeze state before taking the disk-only VM snapshot. Result: %s", vmName, status), e);
+        }
+
+        if (statusObject.has("error")) {
+            throw new IOException(String.format("Failed to verify VM [%s] filesystem freeze state before taking the disk-only VM snapshot. Result: %s", vmName, status));
+        }
+
+        JsonElement returnElement = statusObject.get("return");
+        if (returnElement == null || !returnElement.isJsonPrimitive() || !returnElement.getAsJsonPrimitive().isString()) {
+            throw new IOException(String.format("Failed to verify VM [%s] filesystem freeze state before taking the disk-only VM snapshot. Result: %s", vmName, status));
+        }
+
+        String statusResult = returnElement.getAsString();
         if (!FreezeThawVMCommand.FREEZE.equals(statusResult)) {
             throw new IOException(String.format("Failed to freeze VM [%s] filesystems before taking the disk-only VM snapshot. Status: %s", vmName, statusResult));
         }

plugins/hypervisors/kvm/src/test/java/com/cloud/hypervisor/kvm/resource/wrapper/LibvirtDiskOnlyVMSnapshotCommandWrapperTest.java

@@ -469,6 +469,80 @@ protected boolean thawVmFilesystemsIfNeeded(Domain domain, String vmName) {
         assertTrue("Thaw must be attempted after a successful freeze followed by verification failure", thawCalled[0]);
     }
 
+    @Test
+    public void testVerifyVmFilesystemsFrozenFailsForQemuErrorResponse() throws Exception {
+        LibvirtCreateDiskOnlyVMSnapshotCommandWrapper wrapper = new LibvirtCreateDiskOnlyVMSnapshotCommandWrapper() {
+            @Override
+            protected String getResultOfQemuCommand(String cmd, Domain domain) {
+                return "{\"error\":{\"class\":\"GenericError\",\"desc\":\"guest agent failure\"}}";
+            }
+        };
+
+        try {
+            wrapper.verifyVmFilesystemsFrozen(mock(Domain.class), "vm-name");
+            fail("QEMU guest agent error responses must be treated as IO failures.");
+        } catch (IOException e) {
+            assertTrue(e.getMessage().contains("Failed to verify VM [vm-name] filesystem freeze state"));
+        }
+    }
+
+    @Test
+    public void testTakeDiskOnlyVmSnapshotOfRunningVmReturnsFailureAnswerWhenFreezeStatusJsonIsMalformed() throws Exception {
+        final boolean[] thawCalled = {false};
+        LibvirtCreateDiskOnlyVMSnapshotCommandWrapper wrapper = new LibvirtCreateDiskOnlyVMSnapshotCommandWrapper() {
+            @Override
+            protected Pair<String, java.util.Map<String, Pair<Long, String>>> createSnapshotXmlAndNewVolumePathMap(List<VolumeObjectTO> volumeObjectTOS,
+                    List<com.cloud.hypervisor.kvm.resource.LibvirtVMDef.DiskDef> disks, VMSnapshotTO target, LibvirtComputingResource resource) {
+                return new Pair<>("<domainsnapshot/>", Collections.emptyMap());
+            }
+
+            @Override
+            protected boolean shouldSuspendVmForSnapshot(CreateDiskOnlyVmSnapshotCommand cmd) {
+                return false;
+            }
+
+            @Override
+            protected boolean shouldFreezeVmFilesystemsForSnapshot(CreateDiskOnlyVmSnapshotCommand cmd) {
+                return true;
+            }
+
+            @Override
+            protected void freezeVmFilesystems(Domain domain, String vmName) {
+            }
+
+            @Override
+            protected String getResultOfQemuCommand(String cmd, Domain domain) {
+                return "not-json";
+            }
+
+            @Override
+            protected boolean thawVmFilesystemsIfNeeded(Domain domain, String vmName) {
+                thawCalled[0] = true;
+                return true;
+            }
+        };
+        LibvirtComputingResource resource = mock(LibvirtComputingResource.class);
+        LibvirtUtilitiesHelper libvirtUtilitiesHelper = mock(LibvirtUtilitiesHelper.class);
+        org.libvirt.Connect connect = mock(org.libvirt.Connect.class);
+        Domain domain = mock(Domain.class);
+        CreateDiskOnlyVmSnapshotCommand command = mock(CreateDiskOnlyVmSnapshotCommand.class);
+        VMSnapshotTO target = mock(VMSnapshotTO.class);
+
+        when(command.getVmName()).thenReturn("vm-name");
+        when(command.getVolumeTOs()).thenReturn(List.of());
+        when(command.getTarget()).thenReturn(target);
+        when(resource.getLibvirtUtilitiesHelper()).thenReturn(libvirtUtilitiesHelper);
+        when(libvirtUtilitiesHelper.getConnection()).thenReturn(connect);
+        when(resource.getDisks(connect, "vm-name")).thenReturn(List.of());
+        when(resource.getDomain(connect, "vm-name")).thenReturn(domain);
+
+        CreateDiskOnlyVmSnapshotAnswer answer = (CreateDiskOnlyVmSnapshotAnswer) wrapper.takeDiskOnlyVmSnapshotOfRunningVm(command, resource);
+
+        assertFalse(answer.getResult());
+        assertTrue(answer.getDetails().contains("Failed to verify VM [vm-name] filesystem freeze state"));
+        assertTrue("Thaw must be attempted when freeze verification fails on malformed JSON", thawCalled[0]);
+    }
+
     @Test
     public void testTakeDiskOnlyVmSnapshotOfRunningVmSuspendsBeforeNvramCopyForQuiescedUefiSnapshots() throws Exception {
         List<String> operations = new ArrayList<>();