Hyper-V API: Snapshots feature

.clang-format

@@ -39,6 +39,14 @@ PointerAlignment: Left
 ---
 Language: Cpp
 Standard: c++20
+IncludeCategories:
+  - Regex: '^<windows\.h>$'
+    Priority: 100
+  - Regex: '^<initguid\.h>$'
+    Priority: 200
+  - Regex: '^<virtdisk\.h>$'
+    Priority: 300
+    # "If none of the regular expressions match, INT_MAX is assigned as category."
 ---
 Language: ObjC
 ---

.github/workflows/linux.yml

@@ -217,7 +217,7 @@ jobs:
         # we need to override it at the runner level.
         sudo bash -c 'echo "/coredump/%e.%p.%t" > /proc/sys/kernel/core_pattern'
 
-    - name: Test
+    - name: Run unit tests
       id: test
       if: ${{ matrix.build-type == 'Debug' }}
       timeout-minutes: 2
@@ -237,6 +237,26 @@ jobs:
            LD_LIBRARY_PATH=/root/stage/usr/lib/x86_64-linux-gnu/:/root/stage/lib/:/root/parts/multipass/build/lib/ \
            /root/parts/multipass/build/bin/multipass_tests"
 
+    - name: Run integration tests
+      id: integration-tests
+      if: ${{ matrix.build-type == 'Debug' }}
+      timeout-minutes: 2
+      run: |
+
+        trap 'echo "MULTIPASS_TESTS_EXIT_CODE=$?" >> $GITHUB_ENV' EXIT
+        instance_name=`/snap/bin/lxc --project snapcraft --format=csv --columns=n list | grep multipass`
+        /snap/bin/lxc --project snapcraft start $instance_name | true
+        # Let's print the core pattern so we can check if it's successfully propagated to the container.
+        /snap/bin/lxc --project snapcraft exec $instance_name -- bash -c 'cat /proc/sys/kernel/core_pattern'
+        # Create the directory for the coredumps
+        /snap/bin/lxc --project snapcraft exec $instance_name -- bash -c 'mkdir -p /coredump'
+        # Enable coredumps by setting the core dump size to "unlimited", and run the tests.
+        /snap/bin/lxc --project snapcraft exec $instance_name -- bash -c "\
+           ulimit -c unlimited &&        \
+           env CTEST_OUTPUT_ON_FAILURE=1 \
+           LD_LIBRARY_PATH=/root/stage/usr/lib/x86_64-linux-gnu/:/root/stage/lib/:/root/parts/multipass/build/lib/ \
+           /root/parts/multipass/build/bin/multipass_integration_tests"
+
     - name: Measure coverage
       id: measure-coverage
       if: ${{ matrix.build-type == 'Coverage' }}

.github/workflows/windows-macos.yml

@@ -276,11 +276,16 @@ jobs:
     - name: Build
       run: cmake --build ${{ env.BUILD_DIR }}
 
-    - name: Test
+    - name: Run unit tests
       working-directory: ${{ env.BUILD_DIR }}
       run: |
         bin/multipass_tests
 
+    - name: Run integration tests
+      working-directory: ${{ env.BUILD_DIR }}
+      run: |
+        bin/multipass_integration_tests
+
     - name: Package
       id: cmake-package
       working-directory: ${{ env.BUILD_DIR }}

.gitignore

@@ -29,3 +29,7 @@ packaging/windows/custom-actions/x64/*
 
 # https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html
 CMakeUserPresets.json
+
+# clangd cache path
+.cache/
+**/network-cache

CMakeLists.txt

@@ -88,6 +88,8 @@ if(NOT VCPKG_BUILD_DEFAULT)
   set(VCPKG_HOST_TRIPLET "${VCPKG_HOST_ARCH}-${VCPKG_HOST_OS}-release")
   set(VCPKG_TARGET_TRIPLET "${VCPKG_HOST_ARCH}-${VCPKG_HOST_OS}-release")
 else()
+  set(VCPKG_HOST_TRIPLET "${VCPKG_HOST_ARCH}-${VCPKG_HOST_OS}")
+  set(VCPKG_TARGET_TRIPLET "${VCPKG_HOST_ARCH}-${VCPKG_HOST_OS}")
   message(NOTICE "Will build `vcpkg` deps in both `debug` and `release` configurations. Be aware that it will take around twice the time to build the `vcpkg` deps.")
 endif()
 
@@ -229,6 +231,9 @@ endif()
 # Boost config
 find_package(Boost CONFIG REQUIRED COMPONENTS json)
 
+# Dependencies satisfied by CMake
+include(src/cmake/cmake-deps.cmake)
+
 # OpenSSL config
 find_package(OpenSSL CONFIG REQUIRED)
 
@@ -276,7 +281,12 @@ if(MSVC)
   add_definitions(-DLIBSSH_STATIC) # otherwise adds declspec specifiers to libssh apis
   add_definitions(-D_SILENCE_ALL_CXX17_DEPRECATION_WARNINGS)
   add_definitions(-DWIN32_LEAN_AND_MEAN)
+  add_definitions(-DSECURITY_WIN32)
   set(MULTIPASS_BACKENDS hyperv virtualbox)
+  if(HYPERV_HCS_ENABLED)
+    add_definitions(-DHYPERV_HCS_ENABLED=1)
+    list(APPEND MULTIPASS_BACKENDS hyperv_api)
+  endif()
   set(MULTIPASS_PLATFORM windows)
 else()
   add_compile_options(-Werror -Wall -pedantic -fPIC)

feature-flags.cmake

@@ -16,3 +16,6 @@ include(src/cmake/feature-flag.cmake)
 
 # Multipass backend integrating with Apple Virtualization framework
 feature_flag(APPLEVZ_ENABLED "AppleVZ backend" APPLE)
+
+# The new Windows backend based on Hyper-V Host Compute System / Host Compute Networking APIs
+feature_flag(HYPERV_HCS_ENABLED "Hyper-V HCS backend" WIN32)

include/multipass/constants.h

@@ -75,4 +75,8 @@ constexpr auto petenv_default = "primary";
 constexpr auto timeout_exit_code = 5;
 constexpr auto authenticated_certs_dir = "authenticated-certs";
 constexpr auto home_in_instance = "/home/ubuntu";
+
+constexpr std::chrono::milliseconds vm_shutdown_timeout =
+    300000ms; // unit: ms, 5 minute timeout for shutdown/suspend
+constexpr auto default_ssh_port = 22;
 } // namespace multipass

include/multipass/file_ops.h

@@ -119,19 +119,34 @@ class FileOps : public Singleton<FileOps>
     virtual void copy(const fs::path& src,
                       const fs::path& dist,
                       fs::copy_options copy_options) const;
-    virtual bool exists(const fs::path& path, std::error_code& err) const;
+    virtual void rename(const fs::path& old_p, const fs::path& new_p) const;
+    virtual bool exists(const fs::path& path) const;
+    virtual bool is_symlink(const fs::path& path) const;
+    // [[deprecated("Use non-std::error_code overload instead!")]]
+    virtual bool exists(const fs::path& path, std::error_code& err) const noexcept;
+    // [[deprecated("Use non-std::error_code overload instead!")]]
     virtual bool is_directory(const fs::path& path, std::error_code& err) const;
+    // [[deprecated("Use non-std::error_code overload instead!")]]
     virtual bool create_directory(const fs::path& path, std::error_code& err) const;
+    // [[deprecated("Use non-std::error_code overload instead!")]]
     virtual bool create_directories(const fs::path& path, std::error_code& err) const;
-    virtual bool remove(const fs::path& path, std::error_code& err) const;
+    virtual bool remove(const fs::path& path) const;
+    // [[deprecated("Use non-std::error_code overload instead!")]]
+    virtual bool remove(const fs::path& path, std::error_code& err) const noexcept;
+    // [[deprecated("Use non-std::error_code overload instead!")]]
     virtual void create_symlink(const fs::path& to,
                                 const fs::path& path,
                                 std::error_code& err) const;
+    //[[deprecated("Use non-std::error_code overload instead!")]]
     virtual fs::path read_symlink(const fs::path& path, std::error_code& err) const;
+    //[[deprecated("Use non-std::error_code overload instead!")]]
     virtual fs::file_status status(const fs::path& path, std::error_code& err) const;
+    //[[deprecated("Use non-std::error_code overload instead!")]]
     virtual fs::file_status symlink_status(const fs::path& path, std::error_code& err) const;
+    //[[deprecated("Use non-std::error_code overload instead!")]]
     virtual std::unique_ptr<RecursiveDirIterator>
     recursive_dir_iterator(const fs::path& path, std::error_code& err) const;
+    //[[deprecated("Use non-std::error_code overload instead!")]]
     virtual std::unique_ptr<DirIterator> dir_iterator(const fs::path& path,
                                                       std::error_code& err) const;
     virtual fs::path weakly_canonical(const fs::path& path) const;

include/multipass/network_interface.h

@@ -42,11 +42,9 @@ struct NetworkInterface
 
 inline void tag_invoke(const boost::json::value_from_tag&,
                        boost::json::value& json,
-                       const NetworkInterface& interface)
+                       const NetworkInterface& iface)
 {
-    json = {{"id", interface.id},
-            {"mac_address", interface.mac_address},
-            {"auto_mode", interface.auto_mode}};
+    json = {{"id", iface.id}, {"mac_address", iface.mac_address}, {"auto_mode", iface.auto_mode}};
 }
 
 inline NetworkInterface tag_invoke(const boost::json::value_to_tag<NetworkInterface>&,

include/multipass/signal.h

@@ -28,13 +28,16 @@ struct Signal
     bool wait_for(const T& timeout)
     {
         std::unique_lock<std::mutex> lock{mutex};
-        return cv.wait_for(lock, timeout, [this] { return signaled; });
+        const auto ret = cv.wait_for(lock, timeout, [this] { return signaled; });
+        signaled = false;
+        return ret;
     }
 
     void wait()
     {
         std::unique_lock<decltype(mutex)> lock{mutex};
         cv.wait(lock, [this] { return signaled; });
+        signaled = false;
     }
 
     void signal()

include/multipass/utils/static_bi_map.h

@@ -0,0 +1,47 @@
+/*
+ * Copyright (C) Canonical, Ltd.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+#pragma once
+
+#include <unordered_map>
+
+#include <multipass/disabled_copy_move.h>
+
+namespace multipass
+{
+
+/**
+ * Inefficient, static bidirectional map using two std::unordered_map's.
+ */
+template <typename K, typename V>
+struct static_bi_map : private multipass::DisabledCopyMove
+{
+    static_bi_map(std::initializer_list<std::pair<const K, V>> init)
+        : left(init), right([&init]() {
+              std::unordered_map<V, K> map;
+              for (const auto& [k, v] : init)
+                  map.emplace(v, k);
+              return map;
+          }())
+    {
+    }
+
+    const std::unordered_map<K, V> left;
+    const std::unordered_map<V, K> right;
+};
+
+} // namespace multipass

include/multipass/virtual_machine.h

@@ -21,9 +21,12 @@
 #include "network_interface.h"
 
 #include <QDir>
+#include <fmt/format.h>
 
+#include <cassert>
 #include <chrono>
 #include <condition_variable>
+#include <functional>
 #include <memory>
 #include <mutex>
 #include <string>
@@ -41,6 +44,7 @@ class Snapshot;
 class VirtualMachine : private DisabledCopyMove
 {
 public:
+    // TODO: Get rid of the VirtualMachine::State in favor of InstanceStatus
     enum class State
     {
         off,
@@ -74,7 +78,7 @@ class VirtualMachine : private DisabledCopyMove
     virtual std::string ssh_hostname()
     {
         return ssh_hostname(std::chrono::minutes(2));
-    };
+    }
     virtual std::string ssh_hostname(std::chrono::milliseconds timeout) = 0;
     virtual std::string ssh_username() = 0;
     virtual std::optional<IPAddress> management_ipv4() = 0;
@@ -97,7 +101,8 @@ class VirtualMachine : private DisabledCopyMove
 
     using SnapshotVista = std::vector<std::shared_ptr<const Snapshot>>; // using vista to avoid
                                                                         // confusion with C++ views
-    virtual SnapshotVista view_snapshots() const = 0;
+    using SnapshotPredicate = std::function<bool(const Snapshot&)>;
+    virtual SnapshotVista view_snapshots(SnapshotPredicate predicate = {}) const = 0;
     virtual int get_num_snapshots() const = 0;
 
     virtual std::shared_ptr<const Snapshot> get_snapshot(const std::string& name) const = 0;
@@ -130,3 +135,56 @@ class VirtualMachine : private DisabledCopyMove
     }
 };
 } // namespace multipass
+
+/**
+ * Formatter type specialization for VirtualMachine::State
+ */
+template <typename Char>
+struct fmt::formatter<multipass::VirtualMachine::State, Char>
+{
+    constexpr auto parse(basic_format_parse_context<Char>& ctx)
+    {
+        return ctx.begin();
+    }
+
+    template <typename FormatContext>
+    auto format(multipass::VirtualMachine::State state, FormatContext& ctx) const
+    {
+        std::string_view v = "(undefined)";
+        switch (state)
+        {
+        case multipass::VirtualMachine::State::off:
+            v = "off";
+            break;
+        case multipass::VirtualMachine::State::stopped:
+            v = "stopped";
+            break;
+        case multipass::VirtualMachine::State::starting:
+            v = "starting";
+            break;
+        case multipass::VirtualMachine::State::restarting:
+            v = "restarting";
+            break;
+        case multipass::VirtualMachine::State::running:
+            v = "running";
+            break;
+        case multipass::VirtualMachine::State::delayed_shutdown:
+            v = "delayed_shutdown";
+            break;
+        case multipass::VirtualMachine::State::suspending:
+            v = "suspending";
+            break;
+        case multipass::VirtualMachine::State::suspended:
+            v = "suspended";
+            break;
+        case multipass::VirtualMachine::State::unknown:
+            v = "unknown";
+            break;
+        default:
+            assert(0 && "unhandled VM state");
+            break;
+        }
+
+        return fmt::format_to(ctx.out(), "{}", v);
+    }
+};

src/client/gui/lib/platform/windows.dart

@@ -18,6 +18,7 @@ class WindowsPlatform extends MpPlatform {
   Map<String, String> get drivers => const {
         'hyperv': 'Hyper-V',
         'virtualbox': 'VirtualBox',
+        'hyperv_api': 'Hyper-V (API)'
       };
 
   @override

src/cmake/cmake-deps.cmake

@@ -0,0 +1,25 @@
+# Copyright (C) Canonical, Ltd.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 3 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+include(FetchContent)
+
+# Declare and fetch out_ptr
+# TODO: C++23: Remove this and use std::out_ptr instead.
+FetchContent_Declare(
+  out_ptr
+  GIT_REPOSITORY https://github.com/soasis/out_ptr.git
+  GIT_TAG 02a577edfcf25e2519e380a95c16743b7e5878a1
+)
+
+FetchContent_MakeAvailable(out_ptr)

src/platform/CMakeLists.txt

@@ -30,7 +30,8 @@ function(add_target TARGET_NAME)
       shared_win
       scope_guard
       wineventlogger
-      OpenSSL::applink)
+      OpenSSL::applink
+      Secur32)
   elseif(APPLE)
     add_library(${TARGET_NAME} STATIC
       platform_osx.cpp

src/platform/backends/hyperv/hyperv_virtual_machine.cpp

@@ -426,7 +426,7 @@ mp::VirtualMachine::State mp::HyperVVirtualMachine::current_state()
 
 int mp::HyperVVirtualMachine::ssh_port()
 {
-    return 22;
+    return default_ssh_port;
 }
 
 void mp::HyperVVirtualMachine::handle_state_update()