GitHub - Cadons/libtusclient: libtusclient is a C++ client library for the tus resumable upload protocol, enabling efficient and reliable file uploads with support for resumption, retries, metadata handling, and customizable HTTP backends. (original) (raw)

TusClient: C++ Implementation

libtusclient CI Linux libtusclient CI MacOS libtusclient CI Windows

Overview

Tus is an open-source protocol designed for resumable uploads, distributed under the MIT license. This C++ implementation of the Tus client allows you to perform resumable file uploads to a compatible server using HTTP requests.

The client supports various features to ensure a smooth upload process, including automatic file chunking, caching, asynchronous behavior, and real-time upload progress tracking.

Features

Installation

Prerequisites

Before you begin, ensure that the following tools are installed on your system:

Steps to Install

  1. Clone the repository:
git clone https://github.com/Cadons/libtusclient.git
cd libtusclient
  1. Initialize Vcpkg and install dependencies:

Run the appropriate script for your platform:

• Linux/macOS:

• Windows:

  1. Build the project with CMake: Create a build directory, configure the project, and build it:
mkdir build
cd build
cmake .. --preset {YOUR-SELECTED-PRESET}
cmake --build .
cmake --install .

After completing these steps, you should have the TusClient library built and ready to use.

Open-Source Collaboration

We welcome contributions to this open-source project! If you’d like to contribute, please follow these steps:

  1. Fork the repository on GitHub: https://github.com/Cadons/libtusclient
  2. Clone your fork locally:
git clone https://github.com/Cadons/libtusclient.git
  1. Create a new branch for your feature or bugfix:
git checkout -b feature/my-new-feature
  1. Make your changes and commit them:
git commit -m "Add my new feature"
  1. Push your changes to your fork:
git push origin feature/my-new-feature
  1. Create a pull request from your fork to the main repository.

Library Components

TusClient

The TusClient class is the main class responsible for managing the upload process using the TUS protocol. It provides methods for uploading, canceling, resuming, stopping, and retrying file uploads. It also provides methods for retrieving the upload progress and status. You need to instantiate this class, passing in the required parameters to initiate the upload.

Class Inheritance and Interfaces

HttpClient

The HttpClient class handles all HTTP requests. It is built using curl to manage network communication, ensuring efficient and reliable file uploads. This class provides methods for performing various HTTP methods such as GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS. It also provides a method for aborting a request.

Class Inheritance and Interfaces

FileChunker

The FileChunker class is responsible for splitting the file into smaller chunks to facilitate resumable uploads. It ensures that large files are uploaded in manageable segments. The chunks are stored in a temporary directory and can be loaded from there. The class also provides methods to remove the chunk files and to get the temporary directory.

Class Inheritance and Interfaces

CacheRepository

The CacheRepository class manages the caching of files, helping you avoid re-uploading parts of a file that have already been successfully uploaded. It stores TUSFile objects in a cache file and provides methods to add, remove, and find files in the cache.

Class Inheritance and Interfaces

Verifiers

The Verifiers classes are used to verify the integrity of uploaded files using hashing algorithms like MD5. They ensure that the data uploaded is valid and consistent. The IFileVerifier interface provides methods to compute and verify the hash of a file.

Class Inheritance and Interfaces

Loggers

The ILogger interface allows you to implement custom logging. The default logger is built using EasyLogger, but you can replace it with your own implementation to suit your needs. The EasyLoggingService class provides methods to log messages at different levels such as debug, info, warning, error, and critical.

Class Inheritance and Interfaces

Example

This example demonstrates how to upload a file using the TusClient

#include #include #include <libtusclient/TusClient.h>

// Function to generate a test file (example) std::filesystem::path generateTestFile(int sizeMB) { std::filesystem::path testFilePath = "test_file.txt"; // Create the test file with 'sizeMB' MB content (example implementation) // In a real scenario, you'd populate the file with content std::ofstream file(testFilePath); for (int i = 0; i < sizeMB * 1024 * 1024; ++i) { file.put('A'); // Fill the file with 'A' character (just for testing) } file.close(); return testFilePath; }

int main() { // Generate a test file of size 1MB std::filesystem::path testFilePath = generateTestFile(1); std::cout << "Test file path: " << testFilePath << std::endl;

// Create a TusClient instance with the necessary parameters: app name, server URL, file path, and log level
std::string url = "http://your-tus-server-url"; // Replace with your server URL
TUS::TusClient client("testapp", url, testFilePath, TUS::LogLevel::INFO);

// Perform the upload
std::cout << "Starting upload..." << std::endl;
client.upload();

// Check the status of the upload
if (client.status() == TUS::TusStatus::FINISHED) {
    std::cout << "Upload finished successfully!" << std::endl;
} else {
    std::cout << "Upload failed with status: " << static_cast<int>(client.status()) << std::endl;
}

return 0;

}

We encourage you to submit improvements, bug fixes, or new features via pull requests. If you have a bug report or feature request, feel free to open an issue on the repository page.

This library is distributed under MIT License