feat: add live snapshot API with device ID tracking and layer restacking

This commit introduces a live snapshot feature for overlaybd with the following
key capabilities:

- Add HTTP API server (/snapshot endpoint) for creating snapshots on demand
- Implement create_snapshot() to dynamically restack RW layers
- Add device ID tracking system for image file management
- Support config_path;dev_id format in configuration strings
- Extend LSMT layer management with restack(), index manipulation, and file operations
- Add comprehensive tests for restacking, device registration, and snapshot creation

Co-authored-by: Xun Chen <xunchen@hust.edu.cn>
Co-authored-by: Yifan Yuan <tuji.yyf@alibaba-inc.com>

Signed-off-by: Yifan Yuan <tuji.yyf@alibaba-inc.com>

Author: BigVan

README.md

@@ -60,7 +60,7 @@ To build overlaybd from source code, the following dependencies are required:
 * Libaio, libcurl, libnl3, glib2 and openssl runtime and development libraries.
   * CentOS 7/Fedora: `sudo yum install libaio-devel libcurl-devel openssl-devel libnl3-devel libzstd-static e2fsprogs-devel`
   * CentOS 8: `sudo yum install libaio-devel libcurl-devel openssl-devel libnl3-devel libzstd-devel e2fsprogs-devel`
-  * Debian/Ubuntu: `sudo apt install libcurl4-openssl-dev libssl-dev libaio-dev libnl-3-dev libnl-genl-3-dev libgflags-dev libzstd-dev libext2fs-dev`
+  * Debian/Ubuntu: `sudo apt install libcurl4-openssl-dev libssl-dev libaio-dev libnl-3-dev libnl-genl-3-dev libgflags-dev libzstd-dev libext2fs-dev pkg-config automake libtool # libgtest-dev // for test`
   * Mariner/AzureLinux: `sudo yum install libaio-devel libcurl-devel openssl-devel libnl3-devel e2fsprogs-devel glibc-devel libzstd-devel binutils ca-certificates-microsoft build-essential`
 
 #### Build

src/CMakeLists.txt

@@ -15,6 +15,7 @@ add_library(overlaybd_image_lib
   prefetch.cpp
   tools/sha256file.cpp
   tools/comm_func.cpp
+  api_server.cpp
 )
 target_include_directories(overlaybd_image_lib PUBLIC
   ${CURL_INCLUDE_DIRS}

src/api_server.cpp

@@ -0,0 +1,142 @@
+/*
+   Copyright The Overlaybd Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+#include <photon/net/http/url.h>
+#include <string_view>
+#include "image_service.h"
+#include "image_file.h"
+#include "api_server.h"
+
+int ApiHandler::handle_request(photon::net::http::Request& req,
+                    photon::net::http::Response& resp,
+                    std::string_view) {
+    auto target = req.target(); // string view, format: /snapshot?dev_id=${devID}&config=${config}
+    std::string_view query("");
+    auto pos = target.find('?');
+    if (pos != std::string_view::npos) {
+        query = target.substr(pos + 1);
+    }
+    LOG_DEBUG("Snapshot query: `", query); // string view, format: dev_id=${devID}&config=${config}
+    parse_params(query);
+    auto dev_id = params["dev_id"];
+    auto config_path = params["config"];
+    LOG_DEBUG("dev_id: `, config: `", dev_id, config_path);
+    
+    int code;
+    std::string msg;
+    ImageFile* img_file = nullptr;
+
+    if (dev_id.empty() || config_path.empty()) {
+        code = 400;
+        msg = std::string(R"delimiter({
+    "success": false,
+    "message": "Missing dev_id or config in snapshot request"
+})delimiter");
+        goto EXIT;
+    }
+
+    img_file = imgservice->find_image_file(dev_id);
+    if (!img_file) {
+        code = 404;
+        msg = std::string(R"delimiter({
+    "success": false,
+    "message": "Image file not found"
+})delimiter");
+        goto EXIT;
+    }
+
+    if (img_file->create_snapshot(config_path.c_str()) < 0) {
+        code = 500;
+        msg = std::string(R"delimiter({
+    "success": false,
+    "message": "Failed to create snapshot`"
+})delimiter");
+        goto EXIT;
+    }
+
+    code = 200;
+    msg = std::string(R"delimiter({
+    "success": true,
+    "message": "Snapshot created successfully"
+})delimiter");
+
+EXIT:
+    resp.set_result(code);
+    resp.headers.content_length(msg.size());
+    resp.keep_alive(true);
+    auto ret_w = resp.write((void*)msg.c_str(), msg.size());
+    if (ret_w != (ssize_t)msg.size()) {
+        LOG_ERRNO_RETURN(0, -1, "send body failed, target: `, `", req.target(), VALUE(ret_w));
+    }
+    LOG_DEBUG("send body done");
+    return 0;
+}
+
+void ApiHandler::parse_params(std::string_view query) { // format: dev_id=${devID}&config=${config}...
+    if (query.empty())
+        return;
+    
+    size_t start = 0;
+    while (start < query.length()) {
+        auto end = query.find('&', start);
+        if (end == std::string_view::npos) { // last one
+            end = query.length();
+        }
+        
+        auto param = query.substr(start, end - start);
+        auto eq_pos = param.find('=');
+        if (eq_pos != std::string_view::npos) {
+            auto key = param.substr(0, eq_pos);
+            auto value = param.substr(eq_pos + 1);
+            
+            // url decode
+            auto decoded_key = photon::net::http::url_unescape(key);
+            auto decoded_value = photon::net::http::url_unescape(value);
+            params[decoded_key] = decoded_value;
+        } else {
+            // key without value
+            auto key = photon::net::http::url_unescape(param);
+            params[key] = "";
+        }
+        start = end + 1;
+    }
+}
+
+ApiServer::ApiServer(const std::string &addr, ApiHandler* handler) {
+    photon::net::http::URL url(addr);
+    std::string host = url.host().data(); // the string pointed by data() doesn't end up with '\0'
+    auto pos = host.find(":");
+    if (pos != host.npos) {
+        host.resize(pos);
+    }
+    tcpserver = photon::net::new_tcp_socket_server();
+    tcpserver->setsockopt(SOL_SOCKET, SO_REUSEPORT, 1);
+    if(tcpserver->bind(url.port(), photon::net::IPAddr(host.c_str())) < 0)
+        LOG_ERRNO_RETURN(0, , "Failed to bind api server port `", url.port());
+    if(tcpserver->listen() < 0)
+        LOG_ERRNO_RETURN(0, , "Failed to listen api server port `", url.port());
+    httpserver = photon::net::http::new_http_server();
+    httpserver->add_handler(handler, false, "/snapshot");
+    tcpserver->set_handler(httpserver->get_connection_handler());
+    tcpserver->start_loop();
+    ready = true;
+    LOG_DEBUG("Api server listening on `:`, path: `", host, url.port(), "/snapshot");
+}
+
+ApiServer::~ApiServer() {
+    delete tcpserver;
+    delete httpserver;
+}

src/api_server.h

@@ -0,0 +1,45 @@
+/*
+   Copyright The Overlaybd Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+#pragma once
+
+#include <map>
+#include <string>
+#include <photon/net/http/server.h>
+#include <photon/net/socket.h>
+
+class ImageService;
+
+class ApiHandler : public photon::net::http::HTTPHandler {
+public:
+    ImageService *imgservice;
+    std::map<std::string, std::string> params;
+
+    ApiHandler(ImageService *imgservice) : imgservice(imgservice) {}
+    int handle_request(photon::net::http::Request& req,
+                       photon::net::http::Response& resp,
+                       std::string_view) override;
+    void parse_params(std::string_view query);
+};
+
+struct ApiServer {
+    photon::net::ISocketServer* tcpserver = nullptr;
+    photon::net::http::HTTPServer* httpserver = nullptr;
+    bool ready = false;
+
+    ApiServer(const std::string &addr, ApiHandler* handler);
+    ~ApiServer();
+};

src/config.h

@@ -131,6 +131,12 @@ struct CertConfig : public ConfigUtils::Config {
     APPCFG_PARA(keyFile, std::string, "");
 };
 
+struct ServiceConfig : public ConfigUtils::Config {
+    APPCFG_CLASS
+    APPCFG_PARA(enable, bool, false);
+    APPCFG_PARA(address, std::string, "http://127.0.0.1:9862");
+};
+
 struct GlobalConfig : public ConfigUtils::Config {
     APPCFG_CLASS
 
@@ -155,6 +161,7 @@ struct GlobalConfig : public ConfigUtils::Config {
     APPCFG_PARA(prefetchConfig, PrefetchConfig);
     APPCFG_PARA(certConfig, CertConfig);
     APPCFG_PARA(userAgent, std::string, OVERLAYBD_VERSION);
+    APPCFG_PARA(serviceConfig, ServiceConfig);
 };
 
 struct AuthConfig : public ConfigUtils::Config {
@@ -170,4 +177,5 @@ struct ImageAuthResponse : public ConfigUtils::Config {
 	APPCFG_PARA(data, AuthConfig);
 };
 
+
 } // namespace ImageConfigNS

src/example_config/overlaybd.json

@@ -36,5 +36,9 @@
     },
     "enableAudit": true,
     "auditPath": "/var/log/overlaybd-audit.log",
-    "registryFsVersion": "v2"
+    "registryFsVersion": "v2",
+    "serviceConfig": {
+        "enable": false,
+        "address": "http://127.0.0.1:9862"
+    }
 }

src/image_file.cpp

@@ -334,12 +334,12 @@ LSMT::IFileRO *ImageFile::open_lowers(std::vector<ImageConfigNS::LayerConfig> &l
         return NULL;
 
     photon::join_handle *ths[PARALLEL_LOAD_INDEX];
-    std::vector<IFile *> files;
+    std::vector<IFile *> files; // layer0 ... layerN-1
     files.resize(lowers.size(), nullptr);
     auto n = std::min(PARALLEL_LOAD_INDEX, (int)lowers.size());
     LOG_DEBUG("create ` photon threads to open lowers", n);
 
-    ParallelOpenTask tm(files, lowers.size(), lowers);
+    ParallelOpenTask tm(files, lowers.size(), lowers); // layer0 ... layerN-1
     for (auto i = 0; i < n; ++i) {
         ths[i] =
             photon::thread_enable_join(photon::thread_create11(&do_parallel_open_files, this, tm));
@@ -443,7 +443,7 @@ int ImageFile::init_image_file() {
     ImageConfigNS::UpperConfig upper;
     bool record_no_download = false;
     bool has_error = false;
-    auto lowers = conf.lowers();
+    auto lowers = conf.lowers(); // layer0 ... layerN-1
     auto concurrency = image_service.global_conf.prefetchConfig().concurrency();
 
     if (conf.accelerationLayer() && !conf.recordTracePath().empty()) {
@@ -554,3 +554,51 @@ void ImageFile::set_failed(const Ts &...xs) {
         m_exception = estring().appends(xs...);
     }
 }
+
+int ImageFile::create_snapshot(const char *config_path) {
+    // load new config file to get the snapshot layer path
+    // open new upper layer
+    // restack() current RW layer as snapshot layer
+    if(!m_lower_file || !m_upper_file)
+        LOG_ERROR_RETURN(0, -1, "Lower or upper layer is NULL.");
+
+    ImageConfigNS::ImageConfig new_cfg;
+    LSMT::IFileRW *upper_file = nullptr;
+
+    LOG_INFO("Load new config `.", config_path);
+    if (!new_cfg.ParseJSON(config_path)) {
+        LOG_ERROR_RETURN(0, -1, "Error parse new config json: `.", config_path);
+    }
+
+    auto upper = new_cfg.upper();
+    auto lowers = new_cfg.lowers();
+    // if(lowers[lowers.size()-1].file() != conf.upper().data())
+    //     LOG_ERROR_RETURN(0, -1, "The last lower layer(`) should be the same as old upper layer(`) after restack.", lowers[lowers.size()-1].file(), conf.upper().data());
+    if(upper.index() == conf.upper().index() || upper.data() == conf.upper().data())
+        LOG_ERROR_RETURN(0, -1, "The new upper layer(`, `) should be different from the old upper layer(`, `).", upper.data(), upper.index(), conf.upper().data(), conf.upper().index());
+
+    upper_file = open_upper(upper);
+    if (!upper_file)
+        LOG_ERROR_RETURN(0, -1, "Open upper layer failed.");
+    
+    if(((LSMT::IFileRW *)m_file)->restack(upper_file) != 0)
+        LOG_ERRNO_RETURN(0, -1, "Restack new rwlayer failed.");
+    
+    if(m_upper_file) {
+        // transfer the sealed layer from m_upper_file to m_lower_file before m_upper_file is destructed
+        auto sealed = ((LSMT::IFileRW *)m_upper_file)->get_file(0);
+        ((LSMT::IFileRO *)m_lower_file)->insert_file(sealed);
+        ((LSMT::IFileRW *)m_upper_file)->clear_files();
+        delete m_upper_file;
+    }
+    // set m_lower_file->m_index = m_file->m_index->m_backing_index because m_file is not responsible for the destruction of m_backing_index
+    auto combo_index = (LSMT::IComboIndex *)((LSMT::IFileRW *)m_file)->index(); // m_file->m_index
+    ((LSMT::IFileRO *)m_lower_file)->index(combo_index->backing_index());
+    // set m_file->m_index->m_index0 = upper_file->m_index
+    auto upper_file_index = (LSMT::IMemoryIndex0 *)((LSMT::IFileRW *)upper_file)->index(); // upper_file->m_index
+    combo_index->front_index(upper_file_index);
+
+    m_upper_file = upper_file;
+    
+    return 0;
+}

src/image_file.h

@@ -41,10 +41,15 @@ static std::string SEALED_FILE_NAME = "overlaybd.sealed";
 
 class ImageFile : public photon::fs::ForwardFile {
 public:
-    ImageFile(ImageConfigNS::ImageConfig &_conf, ImageService &is)
+    ImageFile(ImageConfigNS::ImageConfig &_conf, ImageService &is, const std::string &dev_id)
         : ForwardFile(nullptr), image_service(is), m_lower_file(nullptr) {
         conf.CopyFrom(_conf, conf.GetAllocator());
         m_exception = "";
+        if(image_service.register_image_file(dev_id, this) != 0) { // register itself
+            set_failed("duplicated dev id: " + dev_id);
+            return;
+        }
+        m_dev_id = dev_id;
         m_status = init_image_file();
         if (m_status == 1) {
             struct stat st;
@@ -55,6 +60,7 @@ class ImageFile : public photon::fs::ForwardFile {
 
     ~ImageFile() {
         m_status = -1;
+        image_service.unregister_image_file(m_dev_id); // unregister itself
         if (dl_thread_jh != nullptr)
             photon::thread_join(dl_thread_jh);
         delete m_prefetcher;
@@ -113,6 +119,8 @@ class ImageFile : public photon::fs::ForwardFile {
 
     int compact(IFile *as);
 
+    int create_snapshot(const char *config_path);
+
 private:
     Prefetcher *m_prefetcher = nullptr;
     ImageConfigNS::ImageConfig conf;
@@ -121,6 +129,7 @@ class ImageFile : public photon::fs::ForwardFile {
     ImageService &image_service;
     photon::fs::IFile *m_lower_file = nullptr;
     photon::fs::IFile *m_upper_file = nullptr;
+    std::string m_dev_id = "";
 
     int init_image_file();
     template<typename...Ts> void set_failed(const Ts&...xs);