Refactor S3 client implementation. (#15)

Below APIs are added
* MakeBucket()
* RemoveBucket()
* BucketExists()
* ListBuckets()
* StatObject()
* RemoveObject()
* DownloadObject()
* GetObject()
* ListObjects()
* PutObject()
* CopyObject()
* UploadObject()

Signed-off-by: Bala.FA <bala@minio.io>

.github/workflows/cmake.yml

@@ -39,29 +39,38 @@ jobs:
         ./vcpkg-master/bootstrap-vcpkg.sh
         ./vcpkg-master/vcpkg integrate install
 
-    - name: Configure CMake
-      # Configure CMake in a 'build' subdirectory. `CMAKE_BUILD_TYPE` is only required if you are using a single-configuration generator such as make.
-      # See https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html?highlight=cmake_build_type
-      run: cmake -B ${{github.workspace}}/build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}} -DCMAKE_TOOLCHAIN_FILE=${{github.workspace}}/vcpkg-master/scripts/buildsystems/vcpkg.cmake
+    - name: Run debug build
+      run: |
+        cmake -B ./build -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=./vcpkg-master/scripts/buildsystems/vcpkg.cmake
+        cmake --build ./build --config Debug
+
+    - name: Start MinIO server
+      run: |
+        wget --quiet https://dl.min.io/server/minio/release/linux-amd64/minio
+        chmod +x minio
+        mkdir -p ~/.minio/certs
+        cp ./tests/public.crt ./tests/private.key ~/.minio/certs/
+        sudo cp ./tests/public.crt /usr/local/share/ca-certificates/
+        sudo update-ca-certificates
+        MINIO_CI_CD=true ./minio server /tmp/test-xl/{1...4}/ &
+        sleep 10
+
+    - name: Run tests on debug build
+      run: |
+        S3HOST=localhost:9000 ACCESS_KEY=minioadmin SECRET_KEY=minioadmin ./build/tests/tests
 
-    - name: Build
-      # Build your program with the given configuration
+    - name: Run release build
       run: |
-        cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
-        wget --quiet https://dl.min.io/server/minio/release/linux-amd64/minio && chmod +x minio
-        mkdir -p ~/.minio/certs/ && cp testdata/localhost.crt ~/.minio/certs/public.crt && cp testdata/localhost.key ~/.minio/certs/private.key
-        sudo cp testdata/localhost.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates
-        export MINIO_CI_CD=true
-        ./minio server /tmp/test-xl/{1...4}/ & sleep 10
-        export ENDPOINT=https://localhost:9000 ACCESS_KEY=minioadmin SECRET_KEY=minioadmin
-        ${{github.workspace}}/build/examples/s3 -d -a mb -n bucketname
-        ${{github.workspace}}/build/examples/s3 -d -a up -f ${{github.workspace}}/testdata/localhost.crt -n bucketname -k objectname
-        ${{github.workspace}}/build/examples/s3 -d -a down -f /tmp/local.crt -n bucketname -k objectname
-        ${{github.workspace}}/build/examples/s3 -d -a rm -n bucketname -k objectname
-        ${{github.workspace}}/build/examples/s3 -d -a rb -n bucketname
+        cmake --build ./build --target clean
+        cmake -B ./build -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=./vcpkg-master/scripts/buildsystems/vcpkg.cmake
+        cmake --build ./build --config Release
+
+    - name: Run tests on release build
+      run: |
+        S3HOST=localhost:9000 ACCESS_KEY=minioadmin SECRET_KEY=minioadmin ./build/tests/tests
+
     - name: Test
       working-directory: ${{github.workspace}}/build
       # Execute tests defined by the CMake configuration.
       # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
       run: ctest -C ${{env.BUILD_TYPE}}
-

.gitignore

@@ -9,4 +9,12 @@ build/
 *.pc
 .vs
 CMakeSettings.json
-vcpkg_installed/
+vcpkg_installed/
+docs/search
+docs/*html
+docs/*png
+docs/*js
+docs/*css
+docs/*svg
+docs/*map
+docs/*md5

CMakeLists.txt

@@ -29,7 +29,7 @@ macro(set_globals)
 endmacro()
 
 # specify the C++ standard
-set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 
@@ -79,8 +79,8 @@ INCLUDE (CheckIncludeFiles)
 INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR}/include)
 
 SET(MINIOCPP_MAJOR_VERSION "0")
-SET(MINIOCPP_MINOR_VERSION "0")
-SET(MINIOCPP_PATCH_VERSION "1")
+SET(MINIOCPP_MINOR_VERSION "1")
+SET(MINIOCPP_PATCH_VERSION "0")
 
 add_subdirectory(include)
 add_subdirectory(src)
@@ -91,6 +91,11 @@ if (BUILD_EXAMPLES)
     add_subdirectory(examples)
 endif (BUILD_EXAMPLES)
 
+option(BUILD_TESTS "Build tests" ON)
+if (BUILD_TESTS)
+    add_subdirectory(tests)
+endif (BUILD_TESTS)
+
 option(BUILD_DOC "Build documentation" ON)
 
 # check if Doxygen is installed

README.md

@@ -2,63 +2,98 @@
 
 # MinIO C++ Client SDK for Amazon S3 Compatible Cloud Storage [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) [![Sourcegraph](https://sourcegraph.com/github.com/minio/minio-cpp/-/badge.svg)](https://sourcegraph.com/github.com/minio/minio-cpp?badge) [![Apache V2 License](https://img.shields.io/badge/license-Apache%20V2-blue.svg)](https://github.com/minio/minio-cpp/blob/master/LICENSE)
 
-The MinIO C++ Client SDK provides simple APIs to access any Amazon S3 compatible object storage. This quickstart guide will show you how to install the MinIO client SDK, connect to MinIO, and provide a walkthrough for a simple file uploader. For a complete list of APIs and examples, please take a look at the [MinIO C++ Client API Reference](https://minio-cpp.min.io/)
+MinIO C++ SDK is Simple Storage Service (aka S3) client to perform bucket and object operations to any Amazon S3 compatible object storage service.
 
-This document assumes that you have a working C++ development environment. In order to build this project, you need the Cross-Platform Make CMake 3.10 or higher, [vcpkg](https://vcpkg.io/en/index.html).
+For a complete list of APIs and examples, please take a look at the [MinIO C++ Client API Reference](https://minio-cpp.min.io/)
+
+## Build requirements
+* A working C++ development environment supporting C++17 standards.
+* CMake 3.10 or higher.
+* [vcpkg](https://vcpkg.io/en/index.html).
 
 ## Install from `vcpkg`
 ```
 vcpkg install minio-cpp
 ```
 
-## Source build
-
-```
-git clone https://github.com/minio/minio-cpp; cd minio-cpp;
-cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=${VCPKGDIR}/scripts/buildsystems/vcpkg.cmake
-cmake --build build
+## Building source
+```bash
+$ git clone https://github.com/minio/minio-cpp
+$ cd minio-cpp
+$ wget --quiet -O vcpkg-master.zip https://github.com/microsoft/vcpkg/archive/refs/heads/master.zip
+$ unzip -qq vcpkg-master.zip
+$ ./vcpkg-master/bootstrap-vcpkg.sh
+$ ./vcpkg-master/vcpkg integrate install
+$ cmake -B ./build -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=./vcpkg-master/scripts/buildsystems/vcpkg.cmake
+$ cmake --build ./build --config Debug
 ```
 
-## Example code
+## Example:: file-uploader.cc
 ```c++
-#include <iostream>
-#include <fstream>
-#include <stdlib.h>
-#include <getopt.h>
-#include <s3.h>
-
-using namespace Minio;
-
-int
-main ( int argc, char** argv )
-{
-  S3Client s3("https://play.min.io:9000", "minioadmin", "minioadmin");
-  S3ClientIO io;
-  s3.MakeBucket("newbucket", io);
-  if(io.Failure()) {
-    std::cerr << "ERROR: failed to create bucket" << endl;
-    std::cerr << "response:\n" << io << endl;
-    std::cerr << "response body:\n" << io.response.str() << endl;
-    return -1;
+#include <client.h>
+
+int main(int argc, char* argv[]) {
+  // Create S3 base URL.
+  minio::http::BaseUrl base_url;
+  base_url.SetHost("play.min.io");
+
+  // Create credential provider.
+  minio::creds::StaticProvider provider(
+      "Q3AM3UQ867SPQQA43P2F", "zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG");
+
+  // Create S3 client.
+  minio::s3::Client client(base_url, &provider);
+
+  std::string bucket_name = "asiatrip";
+
+  // Check 'asiatrip' bucket exist or not.
+  bool exist;
+  {
+    minio::s3::BucketExistsArgs args;
+    args.bucket_ = bucket_name;
+
+    minio::s3::BucketExistsResponse resp = client.BucketExists(args);
+    if (!resp) {
+      std::cout << "unable to do bucket existence check; " << resp.GetError()
+                << std::endl;
+      return EXIT_FAILURE;
+    }
+
+    exist = resp.exist_;
   }
-  return 0;
-}
-```
 
-## Run an example
-Following example runs 'multipart' upload, uploads a single part. You would have to choose a local file to upload for `-f`, and also remote bucket to upload the object to as `-n` and final object name in the bucket as `-k`.
+  // Make 'asiatrip' bucket if not exist.
+  if (!exist) {
+    minio::s3::MakeBucketArgs args;
+    args.bucket_ = bucket_name;
 
-```
-export ACTION="multipart"
-export ACCESS_KEY=minioadmin
-export SECRET_KEY=minioadmin
-export ENDPOINT="https://play.min.io:9000"
+    minio::s3::MakeBucketResponse resp = client.MakeBucket(args);
+    if (!resp) {
+      std::cout << "unable to create bucket; " << resp.GetError() << std::endl;
+      return EXIT_FAILURE;
+    }
+  }
 
-./examples/s3 -a ${ACTION} -f <local_filename_to_upload> \
-              -n <remote_bucket> -k <remote_objectname>
-```
+  // Upload '/home/user/Photos/asiaphotos.zip' as object name
+  // 'asiaphotos-2015.zip' to bucket 'asiatrip'.
+  minio::s3::UploadObjectArgs args;
+  args.bucket_ = bucket_name;
+  args.object_ = "asiaphotos-2015.zip";
+  args.filename_ = "/home/user/Photos/asiaphotos.zip";
 
-Please choose a `<remote_bucket>` that exists.
+  minio::s3::UploadObjectResponse resp = client.UploadObject(args);
+  if (!resp) {
+    std::cout << "unable to upload object; " << resp.GetError() << std::endl;
+    return EXIT_FAILURE;
+  }
+
+  std::cout << "'/home/user/Photos/asiaphotos.zip' is successfully uploaded as "
+            << "object 'asiaphotos-2015.zip' to bucket 'asiatrip'."
+            << std::endl;
+
+  return EXIT_SUCCESS;
+}
+```
 
 ## License
 This SDK is distributed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0), see [LICENSE](https://github.com/minio/minio-cpp/blob/master/LICENSE) for more information.

check-style.sh

@@ -10,7 +10,7 @@ function clang_format() {
 }
 
 ec=0
-mapfile -t files < <(find . -iname "*.cpp" -o -iname "*.h")
+mapfile -t files < <(find src include examples tests -iname "*.cc" -o -iname "*.h")
 for file in "${files[@]}"; do
     if ! clang_format "$file"; then
         ec=255

docs/Doxyfile.in

@@ -1,5 +1,7 @@
-OUTPUT_DIRECTORY       = @CMAKE_CURRENT_SOURCE_DIR@/docs/
-INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/src/ @CMAKE_CURRENT_SOURCE_DIR@/docs @CMAKE_CURRENT_SOURCE_DIR@/include @CMAKE_CURRENT_SOURCE_DIR@/examples
+OUTPUT_DIRECTORY       = @CMAKE_CURRENT_SOURCE_DIR@/docs
+INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/docs/README.md @CMAKE_CURRENT_SOURCE_DIR@/src @CMAKE_CURRENT_SOURCE_DIR@/include
 PROJECT_NAME           = "MinIO C++ SDK"
 GENERATE_LATEX         = NO
-HTML_OUTPUT = @CMAKE_CURRENT_SOURCE_DIR@/docs/
+WARN_IF_UNDOCUMENTED   = NO
+USE_MDFILE_AS_MAINPAGE = @CMAKE_CURRENT_SOURCE_DIR@/docs/README.md
+HTML_OUTPUT            = @CMAKE_CURRENT_SOURCE_DIR@/docs

docs/README.md

@@ -0,0 +1,97 @@
+> NOTE: This project is work in progress.
+
+MinIO C++ SDK is Simple Storage Service (aka S3) client to perform bucket and object operations to any Amazon S3 compatible object storage service.
+
+For a complete list of APIs and examples, please take a look at the [MinIO C++ Client API Reference](https://minio-cpp.min.io/)
+
+## Build requirements
+* A working C++ development environment supporting C++17 standards.
+* CMake 3.10 or higher.
+* [vcpkg](https://vcpkg.io/en/index.html).
+
+## Install from vcpkg
+```
+vcpkg install minio-cpp
+```
+
+## Building source
+```
+$ git clone https://github.com/minio/minio-cpp
+$ cd minio-cpp
+$ wget --quiet -O vcpkg-master.zip https://github.com/microsoft/vcpkg/archive/refs/heads/master.zip
+$ unzip -qq vcpkg-master.zip
+$ ./vcpkg-master/bootstrap-vcpkg.sh
+$ ./vcpkg-master/vcpkg integrate install
+$ cmake -B ./build -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=./vcpkg-master/scripts/buildsystems/vcpkg.cmake
+$ cmake --build ./build --config Debug
+```
+
+## Example:: file-uploader.cc
+```
+#include <client.h>
+
+int main(int argc, char* argv[]) {
+  // Create S3 base URL.
+  minio::http::BaseUrl base_url;
+  base_url.SetHost("play.min.io");
+
+  // Create credential provider.
+  minio::creds::StaticProvider provider(
+      "Q3AM3UQ867SPQQA43P2F", "zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG");
+
+  // Create S3 client.
+  minio::s3::Client client(base_url, &provider);
+
+  std::string bucket_name = "asiatrip";
+
+  // Check 'asiatrip' bucket exist or not.
+  bool exist;
+  {
+    minio::s3::BucketExistsArgs args;
+    args.bucket_ = bucket_name;
+
+    minio::s3::BucketExistsResponse resp = client.BucketExists(args);
+    if (!resp) {
+      std::cout << "unable to do bucket existence check; " << resp.GetError()
+                << std::endl;
+      return EXIT_FAILURE;
+    }
+
+    exist = resp.exist_;
+  }
+
+  // Make 'asiatrip' bucket if not exist.
+  if (!exist) {
+    minio::s3::MakeBucketArgs args;
+    args.bucket_ = bucket_name;
+
+    minio::s3::MakeBucketResponse resp = client.MakeBucket(args);
+    if (!resp) {
+      std::cout << "unable to create bucket; " << resp.GetError() << std::endl;
+      return EXIT_FAILURE;
+    }
+  }
+
+  // Upload '/home/user/Photos/asiaphotos.zip' as object name
+  // 'asiaphotos-2015.zip' to bucket 'asiatrip'.
+  minio::s3::UploadObjectArgs args;
+  args.bucket_ = bucket_name;
+  args.object_ = "asiaphotos-2015.zip";
+  args.filename_ = "/home/user/Photos/asiaphotos.zip";
+
+  minio::s3::UploadObjectResponse resp = client.UploadObject(args);
+  if (!resp) {
+    std::cout << "unable to upload object; " << resp.GetError() << std::endl;
+    return EXIT_FAILURE;
+  }
+
+  std::cout << "'/home/user/Photos/asiaphotos.zip' is successfully uploaded as "
+            << "object 'asiaphotos-2015.zip' to bucket 'asiatrip'."
+            << std::endl;
+
+  return EXIT_SUCCESS;
+}
+```
+
+## License
+This SDK is distributed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0), see [LICENSE](https://github.com/minio/minio-cpp/blob/master/LICENSE) for more information.