azure_blob_storage.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2021-2025, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include "storage_interface.h"
 
#include <kcenon/pacs/core/dicom_dataset.h>
 
#include <cstddef>
#include <cstdint>
#include <functional>
#include <memory>
#include <mutex>
#include <optional>
#include <shared_mutex>
#include <string>
#include <unordered_map>
 
namespace kcenon::pacs::storage {
 
struct azure_storage_config {
  std::string container_name;
 
  std::string connection_string;
 
  std::optional<std::string> endpoint_suffix;
 
  std::optional<std::string> endpoint_url;
 
  std::size_t block_upload_threshold = 100 * 1024 * 1024;
 
  std::size_t block_size = 4 * 1024 * 1024;
 
  std::size_t max_concurrency = 8;
 
  std::uint32_t connect_timeout_ms = 3000;
 
  std::uint32_t request_timeout_ms = 60000;
 
  bool use_https = true;
 
  std::string access_tier{"Hot"};
 
  std::uint32_t max_retries = 3;
 
  std::uint32_t retry_delay_ms = 1000;
};
 
struct azure_blob_info {
  std::string blob_name;
 
  std::string sop_instance_uid;
 
  std::string study_instance_uid;
 
  std::string series_instance_uid;
 
  std::size_t size_bytes{0};
 
  std::string etag;
 
  std::string content_type{"application/dicom"};
 
  std::string content_md5;
};
 
using azure_progress_callback =
    std::function<bool(std::size_t bytes_transferred, std::size_t total_bytes)>;
 
class azure_blob_storage : public storage_interface {
public:
  // =========================================================================
  // Client Interface (public for backend implementations in .cpp)
  // =========================================================================
 
  class azure_client_interface;
 
  // =========================================================================
  // Construction
  // =========================================================================
 
  explicit azure_blob_storage(const azure_storage_config &config);
 
  ~azure_blob_storage() override;
 
  azure_blob_storage(const azure_blob_storage &) = delete;
  azure_blob_storage &operator=(const azure_blob_storage &) = delete;
 
  azure_blob_storage(azure_blob_storage &&) = delete;
  azure_blob_storage &operator=(azure_blob_storage &&) = delete;
 
  // =========================================================================
  // storage_interface Implementation
  // =========================================================================
 
  [[nodiscard]] auto store(const core::dicom_dataset &dataset)
      -> VoidResult override;
 
  [[nodiscard]] auto retrieve(std::string_view sop_instance_uid)
      -> Result<core::dicom_dataset> override;
 
  [[nodiscard]] auto remove(std::string_view sop_instance_uid)
      -> VoidResult override;
 
  [[nodiscard]] auto exists(std::string_view sop_instance_uid) const
      -> bool override;
 
  [[nodiscard]] auto find(const core::dicom_dataset &query)
      -> Result<std::vector<core::dicom_dataset>> override;
 
  [[nodiscard]] auto get_statistics() const -> storage_statistics override;
 
  [[nodiscard]] auto verify_integrity() -> VoidResult override;
 
  // =========================================================================
  // Azure-specific Operations
  // =========================================================================
 
  [[nodiscard]] auto store_with_progress(const core::dicom_dataset &dataset,
                                         azure_progress_callback callback)
      -> VoidResult;
 
  [[nodiscard]] auto retrieve_with_progress(std::string_view sop_instance_uid,
                                            azure_progress_callback callback)
      -> Result<core::dicom_dataset>;
 
  [[nodiscard]] auto get_blob_name(std::string_view sop_instance_uid) const
      -> std::string;
 
  [[nodiscard]] auto container_name() const -> const std::string &;
 
  [[nodiscard]] auto rebuild_index() -> VoidResult;
 
  [[nodiscard]] auto is_connected() const -> bool;
 
  [[nodiscard]] auto set_access_tier(std::string_view sop_instance_uid,
                                     std::string_view tier) -> VoidResult;
 
private:
  // =========================================================================
  // Internal Helper Methods
  // =========================================================================
 
  [[nodiscard]] auto build_blob_name(std::string_view study_uid,
                                     std::string_view series_uid,
                                     std::string_view sop_uid) const
      -> std::string;
 
  [[nodiscard]] static auto sanitize_uid(std::string_view uid) -> std::string;
 
  [[nodiscard]] auto upload_block_blob(const std::string &blob_name,
                                       const std::vector<std::uint8_t> &data,
                                       azure_progress_callback callback)
      -> VoidResult;
 
  [[nodiscard]] static auto matches_query(const core::dicom_dataset &dataset,
                                          const core::dicom_dataset &query)
      -> bool;
 
  // =========================================================================
  // Member Variables
  // =========================================================================
 
  azure_storage_config config_;
 
  std::unique_ptr<azure_client_interface> client_;
 
  std::unordered_map<std::string, azure_blob_info> index_;
 
  mutable std::shared_mutex mutex_;
};
 
} // namespace kcenon::pacs::storage