updated CHANGELOG.md

CHANGELOG.md

@@ -1,11 +1,24 @@
 # Changelog
 
+## v2.0.5-rc
+
+### Issues
+
+* ~~\#12 [Unit Test] Complete all providers unit tests~~
+* ~~\#21 [Unit Test] Complete WinFSP unit tests~~
+* ~~\#22 [Unit Test] Complete FUSE unit tests~~
+
+### Changes from v2.0.4-rc
+
+* Continue documentation updates
+
 ## v2.0.4-rc
 
 ### BREAKING CHANGES
 
 * `renterd` v2.0.0+ is now required. Prior versions will fail to mount.
 
+<!-- markdownlint-disable-next-line -->
 ### Issues
 
 * \#35 [bug] Low frequency check is set to '0' instead of 1 hour by default

README.md

@@ -6,19 +6,19 @@ on Windows.
 ## Details and Features
 
 * Optimized for [Plex Media Server](https://www.plex.tv/)
-* Single application to mount S3 and/or Sia
+* Remote mounting of `repertory` instances on Linux and Windows
-* Remote mounting of Repertory instances on Linux and Windows
   * Securely share your mounts over TCP/IP via `XChaCha20-Poly1305` with other systems on your network or over the internet.
 * Cross-platform support (Linux 64-bit, Linux arm64/aarch64, Windows 64-bit)
 * Optionally encrypt file names and file data via `XChaCha20-Poly1305` in S3 mounts
 
 ## Minimum Requirements
 
+Only 64-bit operating systems are supported
+
 * [Sia renterd](https://github.com/SiaFoundation/renterd/releases) v2.0.0+ for Sia support
-* Only 64-bit operating systems are supported
+* Linux requires `fusermount3`; otherwise, `repertory` must be manually compiled with `libfuse2` support
-  * By default, Linux requires `fusermount3`; otherwise, `repertory` must be manually compiled with `libfuse2` support
+* Windows requires the following dependencies to be installed:
-  * Windows requires the following dependencies to be installed:
+  * [WinFSP 2023](https://github.com/winfsp/winfsp/releases/download/v2.0/winfsp-2.0.23075.msi)
-    * [WinFSP 2023](https://github.com/winfsp/winfsp/releases/download/v2.0/winfsp-2.0.23075.msi)
 
 ## Supported Operating Systems
 
@@ -28,124 +28,357 @@ on Windows.
 
 ## Usage
 
-### Sia
+### Important Options
-
-* Initial Configuration
-  * Sia steps:
-    * Set the appropriate bucket name and `renterd` API password in `repertory` configuration:
-      * To use `default` as the bucket name and configuration name:
-        * `repertory -set HostConfig.ApiPassword '<my password>'`
-      * To use a different bucket name with `default` as the configuration name:
-        * `repertory -set HostConfig.ApiPassword '<my password>'`
-        * `repertory -set SiaConfig.Bucket '<my bucket>'`
-      * For all other configurations:
-        * `repertory --name '<my config name>' -set HostConfig.ApiPassword '<my password>'`
-        * `repertory --name '<my config name>' -set SiaConfig.Bucket '<my bucket name>'`
-  * To verify/view all configuration options:
-    * `repertory -dc`
-    * `repertory --name '<my config name>' -dc`
-      * Example:
-        * `repertory --name default -dc`
-* Mounting on Linux:
-  * `repertory /mnt/location`
-  * `repertory --name '<my config name>' /mnt/location`
-    * Example:
-      * `repertory --name default /mnt/location`
-* Mounting on Windows:
-  * `repertory t:`
-  * `repertory --name '<my config name>' t:`
-    * Example:
-      * `repertory --name default t:`
-
-### S3
-
-* Initial Configuration
-  * S3 steps:
-    * Set the appropriate base URL:
-      * `repertory -s3 --name '<my config name>' -set S3Config.URL '<my url>'`
-        * Example:
-          * `repertory -s3 --name minio -set S3Config.URL 'http://localhost:9000'`
-    * Set the appropriate bucket name:
-      * `repertory -s3 --name '<my config name>' -set S3Config.Bucket '<my bucket name>'`
-    * Set the appropriate access key:
-      * `repertory -s3 --name '<my config name>' -set S3Config.AccessKey '<my access key>'`
-    * Set the appropriate secret key:
-      * `repertory -s3 --name '<my config name>' -set S3Config.SecretKey '<my secret key>'`
-    * For Sia and most local S3 gateway instances, enable path style URL's:
-      * `repertory -s3 --name '<my config name>' -set S3Config.UsePathStyle true`
-    * Optional steps:
-      * Set an appropriate region. Default is set to `any`:
-        * `repertory -s3 --name '<my config name>' -set S3Config.Region '<my region>'`
-      * Enable encrypted file names and file data. Set a strong, random encryption token and be sure to store it in a secure backup location:
-        * `repertory -s3 --name '<my config name>' -set S3Config.EncryptionToken '<my strong password>'`
-  * To verify/view all configuration options:
-    * `repertory -s3 --name '<my config name>' -dc`
-      * Example:
-        * `repertory -s3 --name minio -dc`
-* Mounting on Linux:
-  * `repertory -s3 --name '<my config name>' /mnt/location`
-    * Example:
-      * `repertory -s3 --name minio /mnt/location`
-* Mounting on Windows:
-  * `repertory -s3 --name '<my config name>' t:`
-    * Example:
-      * `repertory -s3 --name minio t:`
-
-### Notable Options
 
 * `--help`
   * Display all mount utility options
+
+* `-f`
+  * Keep process in foreground on Linux.
+
 * `--name, -na [name]`
+  * Identifies a unique configuration name to support multiple mounts.
   * The `--name` option can be set to any valid value allowed as a file name for your filesystem.
   * For Sia, the bucket name will be set to the same value if it is empty in the configuration file.
     * If the `--name` option is not specified, `default` will be used.
   * For S3, the `--name` option is required and does not affect the bucket name.
+
 * `-dc`
   * Display mount configuration
   * For Sia, `--name` is optional
   * For S3, the `-s3` option is required along with `--name`
 
+### Sia
+
+#### Initial Configuration
+
+* Required steps:
+  * Set the appropriate bucket name and `renterd` API password in `repertory` configuration:
+    * To use `default` as the bucket name and configuration name, you only need to set the `renterd` API password:
+      * `repertory -set HostConfig.ApiPassword '<my password>'`
+    * To specify a different bucket name while using `default` as the configuration name:
+      * `repertory -set HostConfig.ApiPassword '<my password>'`
+      * `repertory -set SiaConfig.Bucket '<my bucket>'`
+    * For all other configurations:
+      * `repertory --name '<my config name>' -set HostConfig.ApiPassword '<my password>'`
+      * `repertory --name '<my config name>' -set SiaConfig.Bucket '<my bucket name>'`
+
+* Optional steps:
+  * Set a custom user name used for basic authentication:
+    * `repertory -set HostConfig.ApiUser '<my user>'`
+    * `repertory --name '<my config name>' -set HostConfig.ApiUser '<my user>'`
+  * Set the `renterd` API port to a value other than `9980`:
+    * `repertory -set HostConfig.ApiPort 9981`
+    * `repertory --name '<my config name>' -set HostConfig.ApiPort 9981`
+  * Set a custom agent string:
+    * `repertory -set HostConfig.AgentString '<my agent>'`
+    * `repertory --name '<my config name>' -set HostConfig.AgentString '<my agent>'`
+
+* To verify/view all configuration options:
+  * `repertory -dc`
+  * `repertory --name '<my config name>' -dc`
+    * Example:
+      * `repertory --name default -dc`
+
+#### Mounting
+
+* Linux:
+  * `repertory /mnt/location`
+  * `repertory --name '<my config name>' /mnt/location`
+    * Example:
+      * `repertory --name default /mnt/location`
+
+* Windows:
+  * `repertory t:`
+  * `repertory --name '<my config name>' t:`
+    * Example:
+      * `repertory --name default t:`
+
+#### Sia configuration file
+
+```json
+{
+  "ApiAuth": "<random generated rpc password>",
+  "ApiPort": 10000,
+  "ApiUser": "repertory",
+  "DatabaseType": "rocksdb",
+  "DownloadTimeoutSeconds": 30,
+  "EnableDownloadTimeout": true,
+  "EnableDriveEvents": false,
+  "EventLevel": "info",
+  "EvictionDelayMinutes": 1,
+  "EvictionUseAccessedTime": false,
+  "HighFreqIntervalSeconds": 30,
+  "HostConfig": {
+    "AgentString": "Sia-Agent",
+    "ApiPassword": "<renterd api password>",
+    "ApiPort": 9980,
+    "ApiUser": "",
+    "HostNameOrIp": "localhost",
+    "Path": "",
+    "Protocol": "http",
+    "TimeoutMs": 60000
+  },
+  "LowFreqIntervalSeconds": 3600,
+  "MaxCacheSizeBytes": 21474836480,
+  "MaxUploadCount": 5,
+  "MedFreqIntervalSeconds": 120,
+  "OnlineCheckRetrySeconds": 60,
+  "PreferredDownloadType": "default",
+  "RemoteMount": {
+    "ApiPort": 20000,
+    "ClientPoolSize": 20,
+    "Enable": false,
+    "EncryptionToken": ""
+  },
+  "RetryReadCount": 6,
+  "RingBufferFileSize": 512,
+  "SiaConfig": {
+    "Bucket": "default"
+  },
+  "TaskWaitMs": 100,
+  "Version": 1
+}
+```
+
+### S3
+
+<!-- markdownlint-disable-next-line -->
+#### Initial Configuration
+
+* Required steps:
+  * Set the appropriate base URL:
+    * `repertory -s3 --name '<my config name>' -set S3Config.URL '<my url>'`
+      * Example:
+        * `repertory -s3 --name minio -set S3Config.URL 'http://localhost:9000'`
+  * Set the appropriate bucket name:
+    * `repertory -s3 --name '<my config name>' -set S3Config.Bucket '<my bucket name>'`
+  * Set the appropriate access key:
+    * `repertory -s3 --name '<my config name>' -set S3Config.AccessKey '<my access key>'`
+  * Set the appropriate secret key:
+    * `repertory -s3 --name '<my config name>' -set S3Config.SecretKey '<my secret key>'`
+  * For Sia and most local S3 gateway instances, enable path style URL's:
+    * `repertory -s3 --name '<my config name>' -set S3Config.UsePathStyle true`
+
+* Optional steps:
+  * Set an appropriate region. Default is set to `any`:
+    * `repertory -s3 --name '<my config name>' -set S3Config.Region '<my region>'`
+  * Enable encrypted file names and file data. Set a strong, random encryption token and be sure to store it in a secure backup location:
+    * `repertory -s3 --name '<my config name>' -set S3Config.EncryptionToken '<my strong password>'`
+
+* To verify/view all configuration options:
+  * `repertory -s3 --name '<my config name>' -dc`
+    * Example:
+      * `repertory -s3 --name minio -dc`
+
+<!-- markdownlint-disable-next-line -->
+#### Mounting
+
+* Linux:
+  * `repertory -s3 --name '<my config name>' /mnt/location`
+    * Example:
+      * `repertory -s3 --name minio /mnt/location`
+
+* Windows:
+  * `repertory -s3 --name '<my config name>' t:`
+    * Example:
+      * `repertory -s3 --name minio t:`
+
+#### S3 configuration file
+
+```json
+{
+  "ApiAuth": "<random generated rpc password>",
+  "ApiPort": 10100,
+  "ApiUser": "repertory",
+  "DatabaseType": "rocksdb",
+  "DownloadTimeoutSeconds": 30,
+  "EnableDownloadTimeout": true,
+  "EnableDriveEvents": false,
+  "EventLevel": "info",
+  "EvictionDelayMinutes": 1,
+  "EvictionUseAccessedTime": false,
+  "HighFreqIntervalSeconds": 30,
+  "LowFreqIntervalSeconds": 3600,
+  "MaxCacheSizeBytes": 21474836480,
+  "MaxUploadCount": 5,
+  "MedFreqIntervalSeconds": 120,
+  "OnlineCheckRetrySeconds": 60,
+  "PreferredDownloadType": "default",
+  "RemoteMount": {
+    "ApiPort": 20100,
+    "ClientPoolSize": 20,
+    "Enable": false,
+    "EncryptionToken": ""
+  },
+  "RetryReadCount": 6,
+  "RingBufferFileSize": 512,
+  "S3Config": {
+    "AccessKey": "<my access key>",
+    "Bucket": "<my bucket name>",
+    "EncryptionToken": "",
+    "Region": "any",
+    "SecretKey": "<my secret key>",
+    "TimeoutMs": 60000,
+    "URL": "http://localhost:9000",
+    "UsePathStyle": true,
+    "UseRegionInURL": false
+  },
+  "TaskWaitMs": 100,
+  "Version": 1
+}
+```
+
 ### Data Directories
 
-* Linux
+#### Linux
-  * `~/.local/repertory2`
+
-* Windows
+* `~/.local/repertory2/s3`
-  * `%LOCALAPPDATA%\repertory2`
+* `~/.local/repertory2/sia`
-    * Example:
+
-      * `C:\Users\Tom\AppData\Local\repertory2`
+#### Windows
-    * IMPORTANT:
+
-      * It is highly recommended to exclude this folder from any anti-virus/anti-malware applications as severe performance issues may arise.
+* `%LOCALAPPDATA%\repertory2\s3`
-      * Excluding the mounted drive letter is also highly recommended.
+* `%LOCALAPPDATA%\repertory2\sia`
+  * Examples:
+    * `C:\Users\Tom\AppData\Local\repertory2\s3`
+    * `C:\Users\Tom\AppData\Local\repertory2\sia`
+* IMPORTANT:
+  * It is highly recommended to exclude this folder from any anti-virus/anti-malware applications as severe performance issues may arise.
+  * Excluding the mounted drive letter is also highly recommended.
 
 ## Remote Mounting
 
-`Repertory` allows local mounts to be shared with other computers on your network.
+`repertory` allows local mounts to be shared with other computers on your network
-This option is referred to as remote mounting. Instructions TBD.
+or over the internet. This option is referred to as remote mounting.
+
+### Server setup
+
+The followings steps must be performed on the mount you wish to share with
+other systems. Changes to configuration will not take affect while a mount is
+active, so it is recommended to unmount beforehand.
+
+* Required steps:
+  * Enable remote mount:
+    * Sia
+      * `repertory -set RemoteMount.Enable true`
+      * `repertory --name '<my config name>' -set RemoteMount.Enable true`
+    * S3:
+      * `repertory -s3 --name '<my config name>' -set RemoteMount.Enable true`
+  * Set a secure encryption token:
+    * Sia:
+      * `repertory -set RemoteMount.EncryptionToken '<my secure password>'`
+      * `repertory --name '<my config name>' -set RemoteMount.EncryptionToken '<my secure password>'`
+    * S3:
+      * `repertory -s3 --name '<my config name>' -set RemoteMount.EncryptionToken '<my secure password>'`
+
+* Optional steps:
+  * Change the port clients will use to connect to your mount:
+    * Sia:
+      * `repertory -set RemoteMount.Port 20000`
+      * `repertory --name '<my config name>' -set RemoteMount.Port 20000`
+    * S3:
+      * `repertory -s3 --name '<my config name>' -set RemoteMount.Port 20000`
+
+IMPORTANT: Be sure to configure your firewall to allow incoming TCP connections
+on the port configured in `RemoteMount.Port`.
+
+#### Remote mount portion of configuration file
+
+```json
+{
+  ...
+  "RemoteMount": {
+    "ApiPort": 20000,
+    "ClientPoolSize": 20,
+    "Enable": true,
+    "EncryptionToken": "<my secure password>"
+  },
+  ...
+}
+```
+
+### Client setup
+
+Client configuration is provider agnostic, so there's no need to specify `-s3`
+for S3 providers.
+
+* Required steps:
+  * Set the encryption token to the same value configured during server setup:
+    * `repertory -rm <host name or IP>:<port> -set RemoteConfig.EncryptionToken '<my secure password>'`
+      * Replace `<host name or IP>` with the host name or IP of the server
+      * Replace `<port>` with the value of `RemoteMount.Port` used in the server configuration
+    * Example:
+      * `repertory -rm 192.168.1.10:20000 -set RemoteConfig.EncryptionToken '<my secure password>'`
+      * `repertory -rm my.host.com:20000 -set RemoteConfig.EncryptionToken '<my secure password>'`
+
+<!-- markdownlint-disable-next-line -->
+#### Mounting
+
+* Linux:
+  * `repertory -rm <host name or IP>:<port> /mnt/location`
+    * Example:
+      * `repertory -rm 192.168.1.10:20000 /mnt/location`
+
+* Windows:
+  * `repertory -rm <host name or IP>:<port> t:`
+    * Example:
+      * `repertory -rm 192.168.1.10:20000 t:`
+
+#### Remote mount configuration file
+```json
+{
+  "ApiAuth": "<random generated rpc password>",
+  "ApiPort": 10010,
+  "ApiUser": "repertory",
+  "EnableDriveEvents": false,
+  "EventLevel": "info",
+  "RemoteConfig": {
+    "ApiPort": 20000,
+    "EncryptionToken": "<my secure password>",
+    "HostNameOrIp": "192.168.1.10",
+    "MaxConnections": 20,
+    "ReceiveTimeoutMs": 120000,
+    "SendTimeoutMs": 30000
+  },
+  "TaskWaitMs": 100,
+  "Version": 1
+}
+```
 
 ## Compiling
 
-* Successful compilation will result in all required files being placed in the `dist/` directory
+Successful compilation will result in all files required for execution to be placed
-* Linux
+in the `dist/` directory
+
+<!-- markdownlint-disable-next-line -->
+### Linux
+
+* Ensure `docker` is installed
+  * For x86_64:
+    * RelWithDebInfo: `scripts/make_unix.sh`
+    * Release: `scripts/make_unix.sh x86_64 Release`
+    * Debug: `scripts/make_unix.sh x86_64 Debug`
+
+  * For aarch64:
+    * RelWithDebInfo: `scripts/make_unix.sh aarch64`
+    * Release: `scripts/make_unix.sh aarch64 Release`
+    * Debug: `scripts/make_unix.sh aarch64 Debug`
+
+<!-- markdownlint-disable-next-line -->
+### Windows
+
+* OFFICIAL: Cross-compiling on Linux
   * Ensure `docker` is installed
-    * For x86_64:
+    * RelWithDebInfo: `scripts/make_win32.sh`
-      * RelWithDebInfo: `scripts/make_unix.sh`
+    * Release: `scripts/make_win32.sh x86_64 Release`
-      * Release: `scripts/make_unix.sh x86_64 Release`
+    * Debug: `scripts/make_win32.sh x86_64 Debug`
-      * Debug: `scripts/make_unix.sh x86_64 Debug`
+
-    * For aarch64:
+* UNOFFICIAL: Compiling on Windows
-      * RelWithDebInfo: `scripts/make_unix.sh aarch64`
+  * Ensure latest [MSYS2](https://www.msys2.org/) is installed
-      * Release: `scripts/make_unix.sh aarch64 Release`
+    * RelWithDebInfo: `scripts\make_win32.cmd`
-      * Debug: `scripts/make_unix.sh aarch64 Debug`
+    * Release: `scripts\make_win32.cmd x86_64 Release`
-* Windows
+    * Debug: `scripts\make_win32.cmd x86_64 Debug`
-  * OFFICIAL: Cross-compiling on Linux
-    * Ensure `docker` is installed
-      * RelWithDebInfo: `scripts/make_win32.sh`
-      * Release: `scripts/make_win32.sh x86_64 Release`
-      * Debug: `scripts/make_win32.sh x86_64 Debug`
-  * UNOFFICIAL: Compiling on Windows
-    * Ensure latest [MSYS2](https://www.msys2.org/) is installed
-      * RelWithDebInfo: `scripts\make_win32.cmd`
-      * Release: `scripts\make_win32.cmd x86_64 Release`
-      * Debug: `scripts\make_win32.cmd x86_64 Debug`
 
 ## Credits
 

config.sh

@@ -10,7 +10,7 @@ PROJECT_DESC="Mount utility for Sia and S3"
 
 PROJECT_MAJOR_VERSION=2
 PROJECT_MINOR_VERSION=0
-PROJECT_REVISION_VERSION=4
+PROJECT_REVISION_VERSION=5
 PROJECT_RELEASE_NUM=0
 PROJECT_RELEASE_ITER=rc
 

repertory/librepertory/include/rpc/client/client.hpp

@@ -48,9 +48,9 @@ public:
 
   [[nodiscard]] auto get_pinned_files() -> rpc_response;
 
-  [[nodiscard]] auto pin_file(const std::string &api_file) -> rpc_response;
+  [[nodiscard]] auto pin_file(const std::string &api_path) -> rpc_response;
 
-  [[nodiscard]] auto pinned_status(const std::string &api_file) -> rpc_response;
+  [[nodiscard]] auto pinned_status(const std::string &api_path) -> rpc_response;
 
   [[nodiscard]] auto set_config_value_by_name(const std::string &name,
                                               const std::string &value)
@@ -58,7 +58,7 @@ public:
 
   [[nodiscard]] auto unmount() -> rpc_response;
 
-  [[nodiscard]] auto unpin_file(const std::string &api_file) -> rpc_response;
+  [[nodiscard]] auto unpin_file(const std::string &api_path) -> rpc_response;
 };
 } // namespace repertory
 

repertory/librepertory/src/rpc/client/client.cpp

@@ -22,8 +22,6 @@
 #include "rpc/client/client.hpp"
 
 #include "types/repertory.hpp"
-#include "utils/base64.hpp"
-#include "utils/utils.hpp"
 
 namespace repertory {
 client::client(rpc_host_info host_info) : host_info_(std::move(host_info)) {}

repertory/librepertory/src/utils/error_utils.cpp

@@ -44,11 +44,13 @@ struct repertory_exception_handler final
   }
 };
 
-std::unique_ptr<repertory_exception_handler> handler{([]() -> auto * {
+const auto repertory_handler{
-  auto *ptr = new repertory_exception_handler{};
+    ([]() -> auto {
-  repertory::utils::error::set_exception_handler(ptr);
+      auto ptr = std::make_unique<repertory_exception_handler>();
-  return ptr;
+      repertory::utils::error::set_exception_handler(ptr.get());
-})()};
+      return ptr;
+    })(),
+};
 } // namespace
 
 namespace repertory::utils::error {