s3_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 cloud_storage_config {
  std::string bucket_name;
 
  std::string region{"us-east-1"};
 
  std::string access_key_id;
 
  std::string secret_access_key;
 
  std::optional<std::string> endpoint_url;
 
  std::size_t multipart_threshold = 100 * 1024 * 1024;
 
  std::size_t part_size = 10 * 1024 * 1024;
 
  std::size_t max_connections = 25;
 
  std::uint32_t connect_timeout_ms = 3000;
 
  std::uint32_t request_timeout_ms = 30000;
 
  bool enable_encryption = false;
 
  std::string storage_class{"STANDARD"};
};
 
struct s3_object_info {
  std::string key;
 
  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"};
};
 
using progress_callback =
    std::function<bool(std::size_t bytes_transferred, std::size_t total_bytes)>;
 
class s3_storage : public storage_interface {
public:
  // =========================================================================
  // Client Interface (public for backend implementations in .cpp)
  // =========================================================================
 
  class s3_client_interface;
 
  // =========================================================================
  // Construction
  // =========================================================================
 
  explicit s3_storage(const cloud_storage_config &config);
 
  ~s3_storage() override;
 
  s3_storage(const s3_storage &) = delete;
  s3_storage &operator=(const s3_storage &) = delete;
 
  s3_storage(s3_storage &&) = delete;
  s3_storage &operator=(s3_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;
 
  // =========================================================================
  // S3-specific Operations
  // =========================================================================
 
  [[nodiscard]] auto store_with_progress(const core::dicom_dataset &dataset,
                                         progress_callback callback)
      -> VoidResult;
 
  [[nodiscard]] auto retrieve_with_progress(std::string_view sop_instance_uid,
                                            progress_callback callback)
      -> Result<core::dicom_dataset>;
 
  [[nodiscard]] auto get_object_key(std::string_view sop_instance_uid) const
      -> std::string;
 
  [[nodiscard]] auto bucket_name() const -> const std::string &;
 
  [[nodiscard]] auto rebuild_index() -> VoidResult;
 
  [[nodiscard]] auto is_connected() const -> bool;
 
private:
  // =========================================================================
  // Internal Helper Methods
  // =========================================================================
 
  [[nodiscard]] auto build_object_key(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_multipart(const std::string &key,
                                      const std::vector<std::uint8_t> &data,
                                      progress_callback callback) -> VoidResult;
 
  [[nodiscard]] static auto matches_query(const core::dicom_dataset &dataset,
                                          const core::dicom_dataset &query)
      -> bool;
 
  // =========================================================================
  // Member Variables
  // =========================================================================
 
  cloud_storage_config config_;
 
  std::unique_ptr<s3_client_interface> client_;
 
  std::unordered_map<std::string, s3_object_info> index_;
 
  mutable std::shared_mutex mutex_;
};
 
} // namespace kcenon::pacs::storage