add basic REST APIs for data retention

Fixes #495

docs/kms.md

@@ -8,7 +8,7 @@ The `secrets` section of the `kms` configuration allows to configure how to encr
 
 - `url` defines the URI to the KMS service
 - `master_key`, defines the master encryption key as string. If not empty, it takes precedence over `master_key_path`.
-- `master_key_path` defines the absolute path to a file containing the master encryption key. This could be, for example, a docker secrets or a file protected with filesystem level permissions.
+- `master_key_path` defines the absolute path to a file containing the master encryption key. This could be, for example, a docker secret or a file protected with filesystem level permissions.
 
 ### Local provider
 

docs/rest-api.md

@@ -1,6 +1,6 @@
 # REST API
 
-SFTPGo exposes REST API to manage, backup, and restore users and folders, and to get real time reports of the active connections with the ability to forcibly close a connection.
+SFTPGo exposes REST API to manage, backup, and restore users and folders, data retention, and to get real time reports of the active connections with the ability to forcibly close a connection.
 
 If quota tracking is enabled in the configuration file, then the used size and number of files are updated each time a file is added/removed. If files are added/removed not using SFTP/SCP, or if you change `track_quota` from `2` to `1`, you can rescan the users home dir and update the used quota using the REST API.
 
@@ -35,6 +35,7 @@ You can create other administrator and assign them the following permissions:
 - manage API keys
 - manage system
 - manage admins
+- manage data retention
 
 You can also restrict administrator access based on the source IP address. If you are running SFTPGo behind a reverse proxy you need to allow both the proxy IP address and the real client IP.
 
@@ -62,6 +63,35 @@ API keys are not allowed for the following REST APIs:
 
 Please keep in mind that using an API key not associated with any administrator it is still possible to create a new administrator, with full permissions, and then impersonate it: be careful if you share unassociated API keys with third parties and with the `manage adminis` permission granted, they will basically allow full access, the only restriction is that the impersonated admin cannot be modified.
 
+The data retention APIs allow you to define per-folder retention policies for each user. To clarify this concept let's show an example, a data retention check accepts a POST body like this one:
+
+```json
+[
+  {
+    "path": "/folder1",
+    "retention": 72
+  },
+  {
+    "path": "/folder1/subfolder",
+    "retention": 0
+  },
+  {
+    "path": "/folder2",
+    "retention": 24
+  }
+]
+```
+
+In the above example we asked to SFTPGo:
+
+- to delete all the files with modification time older than 72 hours in `/folder1`
+- to exclude `/folder1/subfolder`, no files will be deleted here
+- to delete all the files with modification time older than 24 hours in `/folder2`
+
+You can find an example script that shows how to manage data retention [here](../examples/data-retention). Checks the REST API schema for full details.
+
+:warning: Deleting files is an irreversible action, please make sure you fully understand what you are doing before using this feature, you may have users with overlapping home directories or virtual folders shared between multiple users, it is relatively easy to inadvertently delete files you need.
+
 The OpenAPI 3 schema for the exposed API can be found inside the source tree: [openapi.yaml](../httpd/schema/openapi.yaml "OpenAPI 3 specs"). If you want to render the schema without importing it manually, you can explore it on [Stoplight](https://sftpgo.stoplight.io/docs/sftpgo/openapi.yaml).
 
 You can generate your own REST client in your preferred programming language, or even bash scripts, using an OpenAPI generator such as [swagger-codegen](https://github.com/swagger-api/swagger-codegen) or [OpenAPI Generator](https://openapi-generator.tech/).