fixed missing plugin in native image

improved documentation
fixed native image configuration task
2025-02-27 23:30:33 +08:00 · 2025-02-26 21:40:58 +08:00 · 2025-02-26 17:42:02 +08:00 · 2025-02-26 15:26:18 +08:00 · 2025-02-25 22:26:29 +08:00 · 2025-02-25 22:06:52 +08:00
45 changed files with 955 additions and 304 deletions
--- a/.gitea/workflows/build.yaml
+++ b/.gitea/workflows/build.yaml
@@ -39,9 +39,9 @@ jobs:
          push: true
          pull: true
          tags: |
-            gitea.woggioni.net/woggioni/rbcs:latest
-            gitea.woggioni.net/woggioni/rbcs:${{ steps.retrieve-version.outputs.VERSION }}
-          target: release
+            gitea.woggioni.net/woggioni/rbcs:vanilla
+            gitea.woggioni.net/woggioni/rbcs:vanilla-${{ steps.retrieve-version.outputs.VERSION }}
+          target: release-vanilla
          cache-from: type=registry,ref=gitea.woggioni.net/woggioni/rbcs:buildx
      -
        name: Build rbcs memcache Docker image
@@ -58,7 +58,7 @@ jobs:
          cache-from: type=registry,ref=gitea.woggioni.net/woggioni/rbcs:buildx
          cache-to: type=registry,mode=max,compression=zstd,image-manifest=true,oci-mediatypes=true,ref=gitea.woggioni.net/woggioni/rbcs:buildx
      -
-        name: Build rbcs memcache Docker image
+        name: Build rbcs native Docker image
        uses: docker/build-push-action@v5.3.0
        with:
          context: "docker/build/docker"
@@ -66,6 +66,8 @@ jobs:
          push: true
          pull: true
          tags: |
+            gitea.woggioni.net/woggioni/rbcs:latest
+            gitea.woggioni.net/woggioni/rbcs:${{ steps.retrieve-version.outputs.VERSION }}
            gitea.woggioni.net/woggioni/rbcs:native
            gitea.woggioni.net/woggioni/rbcs:native-${{ steps.retrieve-version.outputs.VERSION }}
          target: release-native
--- a/README.md
+++ b/README.md
@@ -1,4 +1,44 @@
 # Remote Build Cache Server
+
+![Release](https://img.shields.io/gitea/v/release/woggioni/rbcs?gitea_url=https%3A%2F%2Fgitea.woggioni.net)
+![Version](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fgitea.woggioni.net%2Fapi%2Fpackages%2Fwoggioni%2Fmaven%2Fnet%2Fwoggioni%2Frbcs-cli%2Fmaven-metadata.xml)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Language](https://img.shields.io/gitea/languages/count/woggioni/rbcs?gitea_url=https%3A%2F%2Fgitea.woggioni.net)
+
+<!--
+![Last commit](https://img.shields.io/gitea/last-commit/woggioni/rbcs?gitea_url=https%3A%2F%2Fgitea.woggioni.net)
+-->
+
+Speed up your builds by sharing and reusing unchanged build outputs across your team.
+
+Remote Build Cache Server (RBCS) allows teams to share and reuse unchanged build and test outputs, 
+significantly reducing build times for both local and CI environments. By eliminating redundant work, 
+RBCS helps teams become more productive and efficient.
+
+**Key Features:**
+- Support for both Gradle and Maven build environments
+- Pluggable storage backends (in-memory, disk-backed, memcached)
+- Flexible authentication (HTTP basic or TLS certificate)
+- Role-based access control
+- Request throttling
+
+## Table of Contents
+- [Quickstart](#quickstart)
+- [Integration with build tools](#integration-with-build-tools)
+  - [Use RBCS with Gradle](#use-rbcs-with-gradle)
+  - [Use RBCS with Maven](#use-rbcs-with-maven)
+- [Server configuration](#server-configuration)
+- [Authentication](#authentication)
+  - [HTTP Basic authentication](#configure-http-basic-authentication)
+  - [TLS client certificate authentication](#configure-tls-certificate-authentication)
+- [Authentication & Access Control](#access-control)
+- [Plugins](#plugins)
+- [Client Tools](#rbcs-client)
+- [Logging](#logging)
+- [FAQ](#faq)
+
+
+
 Remote Build Cache Server (shortened to RBCS) allows you to share and reuse unchanged build 
 and test outputs across the team. This speeds up local and CI builds since cycles are not wasted
 re-building components that are unaffected by new code changes. RBCS supports both Gradle and
@@ -12,9 +52,10 @@ and throttling.

 ## Quickstart

-### Downloading the jar file 
+### Use the all-in-one jar file 
 You can download the latest version from [this link](https://gitea.woggioni.net/woggioni/-/packages/maven/net.woggioni:rbcs-cli/)

+
 Assuming you have Java 21 or later installed, you can launch the server directly with

 ```bash
@@ -24,7 +65,7 @@ java -jar rbcs-cli.jar server
 By default it will start an HTTP server bound to localhost and listening on port 8080 with no authentication,
 writing data to the disk, that you can use for testing

-### Using the Docker image
+### Use the Docker image
 You can pull the latest Docker image with
 ```bash
 docker pull gitea.woggioni.net/woggioni/rbcs:latest
@@ -33,30 +74,16 @@ docker pull gitea.woggioni.net/woggioni/rbcs:latest
 By default it will start an HTTP server bound to localhost and listening on port 8080 with no authentication,
 writing data to the disk, that you can use for testing

-## Usage
+### Use the native executable
+If you are on a Linux X86_64 machine you can download the native executable
+from [here](https://gitea.woggioni.net/woggioni/-/packages/maven/net.woggioni:rbcs-cli/).
+It behaves the same as the jar file but it doesn't require a JVM and it has faster startup times.
+becausue of GraalVm's [closed-world assumption](https://www.graalvm.org/latest/reference-manual/native-image/basics/#static-analysis),
+the native executable does not supports plugins, so it comes with all plugins embedded into it.

-### Configuration
-The location of the `rbcs.xml` configuration file depends on the operating system, 
-Alternatively it can be changed setting the `RBCS_CONFIGURATION_DIR` environmental variable or `net.woggioni.rbcs.conf.dir` Java system property
-to the directory that contain the `rbcs.xml` file.
+## Integration with build tools

-The server configuration file follows the XML format and uses XML schema for validation
-(you can find the schema for the main configuration file [here](https://gitea.woggioni.net/woggioni/rbcs/src/branch/master/rbcs-server/src/main/resources/net/woggioni/rbcs/server/schema/rbcs.xsd)).
-
-The configuration values are enclosed inside XML attribute and support system property / environmental variable interpolation.
-As an example, you can configure RBCS to read the server port number from the `RBCS_SERVER_PORT` environmental variable
-and the bind address from the `rbc.bind.address` JVM system property with.
-
-Full documentation for all tags and attributes is available [here](doc/server_configuration.md).
-
-### Plugins
-If you want to use memcache as a storage backend you'll also need to download [the memcache plugin](https://gitea.woggioni.net/woggioni/-/packages/maven/net.woggioni:rbcs-server-memcache/)
-
-Plugins need to be stored in a folder named `plugins` in the located server's working directory
-(the directory where the server process is started). They are shipped as TAR archives, so you need to extract
-the content of the archive into the `plugins` directory for the server to pick them up.
-
-### Using RBCS with Gradle 
+### Use RBCS with Gradle

 Add this to the `settings.gradle` file of your project

@@ -101,7 +128,7 @@ add `org.gradle.caching=true` to your `<project>/gradle.properties` or run gradl

 Read [Gradle documentation](https://docs.gradle.org/current/userguide/build_cache.html) for more detailed information.

-### Using RBCS with Maven
+### Use RBCS with Maven

 1. Create an `extensions.xml` in `<project>/.mvn/extensions.xml` with the following content
  ```xml
@@ -128,10 +155,198 @@ Read [Gradle documentation](https://docs.gradle.org/current/userguide/build_cach

 Alternatively you can set those properties in your `<project>/pom.xml`

-
 Read [here](https://maven.apache.org/extensions/maven-build-cache-extension/remote-cache.html)
 for more informations

+
+## Server configuration
+RBCS reads an XML configuration file, by default named `rbcs-server.xml`.
+The expected location of the `rbcs-server.xml` file depends on the operating system,
+if the configuration file is not found a default one will be created and its location is printed
+on the console
+
+```bash
+user@76a90cbcd75d:~$ rbcs-cli server
+2025-01-01 00:00:00,000 [INFO ] (main) n.w.r.c.impl.commands.ServerCommand -- Creating default configuration file at '/home/user/.config/rbcs/rbcs-server.xml'
+```
+
+Alternatively it can be changed setting the `RBCS_CONFIGURATION_DIR` environmental variable or `net.woggioni.rbcs.conf.dir` 
+Java system property to the directory that contain the `rbcs-server.xml` file.
+It can also be directly specified from the command line with
+```bash
+java -jar rbcs-cli.jar server -c /path/to/rbcs-server.xml
+```
+
+The server configuration file follows the XML format and uses XML schema for validation
+(you can find the schema for the `rbcs-server.xml` configuration file [here](https://gitea.woggioni.net/woggioni/rbcs/src/branch/master/rbcs-server/src/main/resources/net/woggioni/rbcs/server/schema/rbcs-server.xsd)).
+
+The configuration values are enclosed inside XML attribute and support system property / environmental variable interpolation.
+As an example, you can configure RBCS to read the server port number from the `RBCS_SERVER_PORT` environmental variable
+and the bind address from the `rbc.bind.address` JVM system property with
+
+```xml
+<bind host="${sys:rpc.bind.address}" port="${env:RBCS_SERVER_PORT}"/>
+```
+
+Full documentation for all tags and attributes and configuration file examples
+are available [here](doc/server_configuration.md).
+
+### Plugins
+If you want to use memcache as a storage backend you'll also need to download [the memcache plugin](https://gitea.woggioni.net/woggioni/-/packages/maven/net.woggioni:rbcs-server-memcache/)
+
+Plugins need to be stored in a folder named `plugins` in the located server's working directory
+(the directory where the server process is started). They are shipped as TAR archives, so you need to extract
+the content of the archive into the `plugins` directory for the server to pick them up.
+
+## Authentication
+
+RBCS supports 2 authentication mechanisms:
+
+- HTTP basic authentication
+- TLS certificate authentication
+
+### Configure HTTP basic authentication
+
+Add a `<basic>` element to the `<authentication>` element in your `rbcs-server.xml`
+```xml
+    <authentication>
+      <basic/>
+    </authentication>
+```
+
+### Configure TLS certificate authentication
+
+Add a `<client-certificate>` element to the `<authentication>` element in your `rbcs-server.xml`
+```xml
+    <authentication>
+        <client-certificate>
+            <user-extractor attribute-name="CN" pattern="(.*)"/>
+            <group-extractor attribute-name="O" pattern="(.*)"/>
+        </client-certificate>
+    </authentication>
+```
+The `<user-extractor>` here determines how the username is extracted from the
+subject's X.500 name in the TLS certificate presented by the client, where `attribute-name`
+is the `RelativeDistinguishedName` (RDN) identifier and pattern is a regular expression
+that will be applied to extract the username from the first group present in the regex.
+An error will be thrown if the regular expression contains no groups, while additional
+groups are ignored.
+
+Similarly, the `<group-extractor>` here determines how the group name is extracted from the
+subject's X.500 name in the TLS certificate presented by the client. 
+Note that this allows to assign roles to incoming requests without necessarily assigning them
+a username.
+
+
+
+## Access control
+
+RBCS supports role-based access control (RBAC), three roles are available:
+- `Reader` can perform `GET` calls
+- `Writer` can perform `PUT` calls
+- `Healthcheck` can perform `TRACE` calls
+
+Roles are assigned to groups so that a user will have a role only if that roles belongs
+to one of the groups he is a member of.
+
+There is also a special `<anonymous>` user 
+which matches any request who hasn't been authenticated and that can be assigned
+to any group like a normal user. This permits to have a build cache that is
+publicly readable but only writable by authenticated users (e.g. CI/CD pipeline).
+
+### Defining users
+
+Users can be defined in the `<authorization>` element
+```xml
+    <authorization>
+        <users>
+            <user name="user1" password="kb/vNnkn2RvyPkTN6Q07uH0F7wI7u61MkManD3NHregRukBg4KHehfbqtLTb39fZjHA+SRH+EpEWDCf+Rihr5H5C1YN5qwmArV0p8O5ptC4="/>
+            <user name="user2" password="2J7MAhdIzZ3SO+JGB+K6wPhb4P5LH1L4L7yJCl5QrxNfAWRr5jTUExJRbcgbH1UfnkCbIO1p+xTDq+FCj3LFBZeMZUNZ47npN+WR7AX3VTo="/>
+            <anonymous/>
+        </users>
+        <groups>
+            <group name="readers">
+                <users>
+                    <anonymous/>
+                </users>
+                <roles>
+                    <reader/>
+                </roles>
+            </group>
+            <group name="writers">
+                <users>
+                    <user ref="user1"/>
+                    <user ref="user2"/>
+                </users>
+                <roles>
+                    <reader/>
+                    <writer/>
+                    <healthcheck/>
+                </roles>
+            </group>
+        </groups>
+    </authorization>
+```
+
+The `password` attribute is only used for HTTP Basic authentication, so it can be omitted
+if you use TLS certificate authentication. It must contain a password hash that can be derived from
+the actual password using the following command
+
+```bash
+java -jar rbcs-cli.jar password
+```
+
+## Reliability
+
+RBCS implements the [TRACE](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/TRACE) HTTP method and this functionality can be used
+as a health check (mind you need to have `Healthcheck` role in order to perform it and match the server's `prefix` in the URL).
+
+## RBCS Client
+
+RBCS ships with a command line client that can be used for testing, benchmarking or to manually 
+upload/download files to the cache. It must be configured with the `rbcs-client.xml`, 
+whose location follows the same logic of the `rbcs-server.xml`. 
+The `rbcs-client.xml` must adhere to the [rbcs-client.xsd](rbcs-client/src/main/resources/net/woggioni/rbcs/client/schema/rbcs-client.xsd) 
+XML schema
+
+The documentation for the `rbcs-client.xml` configuration file is available [here](conf/client_configuration.md)
+
+### GET command
+
+```bash
+java -jar rbcs-cli.jar client -p $CLIENT_PROFILE_NAME get -k $CACHE_KEY -v $FILE_WHERE_THE_VALUE_WILL_BE_STORED
+```
+
+### PUT command
+
+```bash
+java -jar rbcs-cli.jar client -p $CLIENT_PROFILE_NAME put -k $CACHE_KEY -v $FILE_TO_BE_UPLOADED
+```
+
+If you don't specify the key, a UUID key based on the file content will be used, 
+if you add the `-i` command line parameter, the uploaded file will be served with
+`Content-Disposition: inline` HTTP header so that browser will attempt to render 
+it in the page instead of triggering a file download (in this way you can create a temporary web page).
+
+The client will try to detect the file mime type upon upload but if you want to be sure you can specify
+it manually with the `-t` parameter. 
+
+### Benchmark command
+
+```bash
+java -jar rbcs-cli.jar client -p $CLIENT_PROFILE_NAME benchamrk -s 4096 -e 10000
+```
+This will insert 10000 randomly generates entries of 4096 bytes into RBCS, then retrieve them
+and check that the retrieved value matches what was inserted. 
+It will also print throughput stats on the way.
+
+## Logging
+
+RBCS uses [logback](https://logback.qos.ch/) and ships with a [default logging configuration](./conf/logback.xml) that
+can be overridden with `-Dlogback.configurationFile=path/to/custom/configuration.xml`, refer to
+[Logback documentation](https://logback.qos.ch/manual/configuration.html) for more details about
+how to configure Logback
+
 ## FAQ
 ### Why should I use a build cache?

--- a/doc/client_configuration.md
+++ b/doc/client_configuration.md
@@ -0,0 +1,125 @@
+# XML Schema Documentation: RBCS Client Configuration
+
+This document provides detailed information about the XML schema for RBCS client configuration, which defines profiles for connecting to RBCS servers.
+
+## Root Element
+
+### `profiles`
+The root element that contains a collection of server profiles.
+- **Type**: `profilesType`
+- **Contains**: Zero or more `profile` elements
+
+## Complex Types
+
+### `profilesType`
+Defines the structure for the profiles collection.
+- **Elements**:
+    - `profile`: Server connection profile (0 to unbounded)
+
+### `profileType`
+Defines a server connection profile with authentication, connection settings, and retry policies.
+
+- **Attributes**:
+    - `name` (required): Name of the server profile, referenced with the '-p' parameter in rbcs-cli
+    - `base-url` (required): RBCs server URL
+    - `max-connections`: Maximum number of concurrent TCP connections (default: 50)
+    - `connection-timeout`: Timeout for establishing connections
+    - `enable-compression`: Whether to enable HTTP compression (default: true)
+
+- **Elements** (in sequence):
+    - **Authentication** (choice of one):
+        - `no-auth`: Disable authentication
+        - `basic-auth`: Enable HTTP basic authentication
+        - `tls-client-auth`: Enable TLS certificate authentication
+    - `connection` (optional): Connection timeout settings
+    - `retry-policy` (optional): Retry policy for failed requests
+    - `tls-trust-store` (optional): Custom truststore for server certificate validation
+
+### `connectionType`
+Defines connection timeout settings.
+
+- **Attributes**:
+    - `idle-timeout`: Close connection after inactivity period (default: PT30S - 30 seconds)
+    - `read-idle-timeout`: Close connection when no read occurs (default: PT60S - 60 seconds)
+    - `write-idle-timeout`: Close connection when no write occurs (default: PT60S - 60 seconds)
+
+### `noAuthType`
+Indicates no authentication should be used.
+- No attributes or elements
+
+### `basicAuthType`
+Configures HTTP Basic Authentication.
+
+- **Attributes**:
+    - `user` (required): Username for authentication
+    - `password` (required): Password for authentication
+
+### `tlsClientAuthType`
+Configures TLS client certificate authentication.
+
+- **Attributes**:
+    - `key-store-file` (required): Path to the keystore file
+    - `key-store-password` (required): Password to open the keystore
+    - `key-alias` (required): Alias of the keystore entry with the private key
+    - `key-password` (optional): Private key entry's encryption password
+
+### `retryType`
+Defines retry policy using exponential backoff.
+
+- **Attributes**:
+    - `max-attempts` (required): Maximum number of retry attempts
+    - `initial-delay`: Delay before first retry (default: PT1S - 1 second)
+    - `exp`: Exponent for computing next delay (default: 2.0)
+
+### `trustStoreType`
+Configures custom truststore for server certificate validation.
+
+- **Attributes**:
+    - `file` (required): Path to the truststore file
+    - `password`: Truststore file password
+    - `check-certificate-status`: Whether to check certificate validity using CRL/OCSP
+    - `verify-server-certificate`: Whether to validate server certificates (default: true)
+
+## Sample XML Document
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<profiles xmlns="urn:net.woggioni.rbcs.client">
+  <!-- Profile with basic authentication -->
+  <profile name="production-server" 
+           base-url="https://rbcs.example.com/api" 
+           max-connections="100" 
+           enable-compression="true">
+    <basic-auth user="admin" password="secure_password123"/>
+    <connection idle-timeout="PT45S" 
+                read-idle-timeout="PT90S" 
+                write-idle-timeout="PT90S"/>
+    <retry-policy max-attempts="5" 
+                 initial-delay="PT2S" 
+                 exp="1.5"/>
+    <tls-trust-store file="/path/to/truststore.jks" 
+                    password="truststore_password" 
+                    check-certificate-status="true"/>
+  </profile>
+  
+  <!-- Profile with TLS client authentication -->
+  <profile name="secure-server" 
+           base-url="https://secure.example.com/api" 
+           max-connections="25">
+    <tls-client-auth key-store-file="/path/to/keystore.p12" 
+                    key-store-password="keystore_password" 
+                    key-alias="client-cert" 
+                    key-password="key_password"/>
+    <retry-policy max-attempts="3"/>
+  </profile>
+  
+  <!-- Profile with no authentication -->
+  <profile name="development" 
+           base-url="http://localhost:8080/api" 
+           enable-compression="false">
+    <no-auth/>
+  </profile>
+</profiles>
+```
+
+This sample XML document demonstrates three different profiles with various authentication methods and configuration options as defined in the schema.
--- a/doc/server_configuration.md
+++ b/doc/server_configuration.md
@@ -1,4 +1,3 @@
-
 ### RBCS server configuration file elements and attributes

 #### Root Element: `server`
@@ -109,6 +108,7 @@ Configures TLS encryption.
    - `password`: Keystore password
    - `key-alias` (required): Private key alias
    - `key-password`: Private key password
+
 - `<truststore>`: Client certificate verification

    **Attributes:**  
@@ -126,7 +126,7 @@ Configures TLS encryption.
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <rbcs:server xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:rbcs="urn:net.woggioni.rbcs.server"
-             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs.xsd"
+             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd"
 >
    <bind host="0.0.0.0" port="8080" incoming-connections-backlog-size="1024"/>
    <connection
@@ -137,8 +137,21 @@ Configures TLS encryption.
            read-timeout="PT5S"
            write-timeout="PT5S"/>
    <event-executor use-virtual-threads="true"/>
+  
    <cache xs:type="rbcs:inMemoryCacheType" max-age="P7D" enable-compression="false" max-size="0x10000000" />
-    <!--cache xs:type="rbcs:fileSystemCacheType" max-age="P7D" enable-compression="false" path="${sys:java.io.tmpdir}/rbcs"/-->
+  
+  <!-- uncomment this to enable the filesystem storage backend, sotring cache data in "${sys:java.io.tmpdir}/rbcs"
+    <cache xs:type="rbcs:fileSystemCacheType" max-age="P7D" enable-compression="false" path="${sys:java.io.tmpdir}/rbcs"/>
+  -->
+
+  <!-- uncomment this to use memcache as the storage backend, also make sure you have 
+       the memcache plugin installed in the `plugins` directory if you are using running
+       the jar version of RBCS
+  <cache xs:type="rbcs-memcache:memcacheCacheType" max-age="P7D" chunk-size="0x1000" digest="MD5">
+    <server host="127.0.0.1" port="11211" max-connections="256"/>
+  </cache>
+  -->
+
  <authorization>
        <users>
            <user name="user1" password="II+qeNLft2pZ/JVNo9F7jpjM/BqEcfsJW27NZ6dPVs8tAwHbxrJppKYsbL7J/SMl">
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -3,7 +3,7 @@ RUN adduser -D luser
 USER luser
 WORKDIR /home/luser

-FROM base-release AS release
+FROM base-release AS release-vanilla
 ADD rbcs-cli-envelope-*.jar rbcs.jar
 ENTRYPOINT ["java", "-XX:+UseSerialGC", "-XX:GCTimeRatio=24", "-jar", "/home/luser/rbcs.jar", "server"]

@@ -17,5 +17,7 @@ ADD logback.xml .
 ENTRYPOINT ["java", "-Dlogback.configurationFile=logback.xml", "-XX:+UseSerialGC", "-XX:GCTimeRatio=24", "-jar", "/home/luser/rbcs.jar", "server"]

 FROM scratch AS release-native
-ADD rbcs-cli.upx rbcs-cli
-ENTRYPOINT ["./rbcs-cli"]
+ADD rbcs-cli.upx /rbcs/rbcs-cli
+ENV RBCS_CONFIGURATION_DIR="/rbcs"
+WORKDIR /rbcs
+ENTRYPOINT ["/rbcs/rbcs-cli"]
--- a/docker/README.md
+++ b/docker/README.md
@@ -0,0 +1,24 @@
+# RBCS Docker images
+There are 3 image flavours:
+- vanilla
+- memcache
+- native
+
+The `vanilla` image only contains the envelope 
+jar file with no plugins and is based on `eclipse-temurin:21-jre-alpine`
+
+The `memcache` image is similar to the `vanilla` image, except that it also contains
+the `rbcs-server-memcache` plugin in the `plugins` folder, use this image if you don't want to use the `native`
+image and want to use memcache as the cache backend
+
+The `native` image contains a native, statically-linked executable created with GraalVM
+that has no userspace dependencies. It also embeds the memcache plugin inside the executable.
+Use this image for maximum efficiency and minimal memory footprint. 
+
+## Which image shoud I use?
+The `native` image uses Java's SerialGC, so it's ideal for constrained environment like containers or small servers,
+if you have a lot of resources and want to squeeze out the maximum throughput you should consider the
+`vanilla` or `memcache` image, then choose and fine tune the garbage collector.
+
+Also the `native` image is only available for the `x86_64` architecture at the moment, 
+while `vanilla` and `memcache` also ship a `aarch64` variant.
--- a/gradle.properties
+++ b/gradle.properties
@@ -4,7 +4,7 @@ org.gradle.caching=true

 rbcs.version = 0.2.0

-lys.version = 2025.02.25
+lys.version = 2025.02.26

 gitea.maven.url = https://gitea.woggioni.net/api/packages/woggioni/maven
 docker.registry.url=gitea.woggioni.net
--- a/rbcs-api/src/main/java/net/woggioni/rbcs/api/Role.java
+++ b/rbcs-api/src/main/java/net/woggioni/rbcs/api/Role.java
@@ -1,5 +1,5 @@
 package net.woggioni.rbcs.api;

 public enum Role {
-    Reader, Writer
+    Reader, Writer, Healthcheck
 }
--- a/rbcs-cli/build.gradle
+++ b/rbcs-cli/build.gradle
@@ -90,13 +90,21 @@ Provider<EnvelopeJarTask> envelopeJarTaskProvider = tasks.named(EnvelopePlugin.E
 }

 tasks.named(NativeImagePlugin.CONFIGURE_NATIVE_IMAGE_TASK_NAME, NativeImageConfigurationTask) {
+    javaLauncher = javaToolchains.launcherFor {
+        languageVersion = JavaLanguageVersion.of(21)
+        vendor = JvmVendorSpec.ORACLE
+    }
+
    mainClass = "net.woggioni.rbcs.cli.graal.GraalNativeImageConfiguration"
-    setClasspath(configurations.configureNativeImageRuntimeClasspath + sourceSets.graal.output.classesDirs)
+    classpath = project.files(
+        configurations.configureNativeImageRuntimeClasspath,
+        sourceSets.configureNativeImage.output
+    )
    mergeConfiguration = false
    systemProperty('logback.configurationFile', 'classpath:net/woggioni/rbcs/cli/logback.xml')
    systemProperty('io.netty.leakDetectionLevel', 'DISABLED')
    modularity.inferModulePath = false
-    enabled = false
+    enabled = true
 }

 nativeImage {
--- a/rbcs-cli/conf/rbcs-client.xml
+++ b/rbcs-cli/conf/rbcs-client.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<rbcs-client:profiles xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
+                      xmlns:rbcs-client="urn:net.woggioni.rbcs.client"
+                      xs:schemaLocation="urn:net.woggioni.rbcs.client jpms://net.woggioni.rbcs.client/net/woggioni/rbcs/client/schema/rbcs-client.xsd"
+>
+    <profile name="profile1" base-url="https://rbcs1.example.com/">
+        <no-auth/>
+        <connection write-idle-timeout="PT60S"
+                    read-idle-timeout="PT60S"
+                    idle-timeout="PT30S" />
+    </profile>
+    <profile name="profile2" base-url="https://rbcs2.example.com/">
+        <basic-auth user="user" password="password"/>
+    </profile>
+</rbcs-client:profiles>
--- a/rbcs-cli/conf/rbcs-server.xml
+++ b/rbcs-cli/conf/rbcs-server.xml
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<rbcs:server xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
+             xmlns:rbcs="urn:net.woggioni.rbcs.server"
+             xmlns:rbcs-memcache="urn:net.woggioni.rbcs.server.memcache"
+             xs:schemaLocation="urn:net.woggioni.rbcs.server.memcache jpms://net.woggioni.rbcs.server.memcache/net/woggioni/rbcs/server/memcache/schema/rbcs-memcache.xsd urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd"
+>
+    <bind host="127.0.0.1" port="8080" incoming-connections-backlog-size="1024"/>
+    <connection
+            max-request-size="67108864"
+            idle-timeout="PT10S"
+            read-idle-timeout="PT20S"
+            write-idle-timeout="PT20S"/>
+    <event-executor use-virtual-threads="true"/>
+    <cache xs:type="rbcs-memcache:memcacheCacheType" max-age="P7D" chunk-size="0x1000" digest="MD5">
+        <server host="127.0.0.1" port="11211" max-connections="256"/>
+    </cache>
+    <!--cache xs:type="rbcs:inMemoryCacheType" max-age="P7D" enable-compression="false" max-size="0x10000000" /-->
+    <!--cache xs:type="rbcs:fileSystemCacheType" max-age="P7D" enable-compression="false" /-->
+    <authorization>
+        <users>
+            <user name="woggioni" password="II+qeNLft2pZ/JVNo9F7jpjM/BqEcfsJW27NZ6dPVs8tAwHbxrJppKYsbL7J/SMl">
+                <quota calls="100" period="PT1S"/>
+            </user>
+            <user name="gitea" password="v6T9+q6/VNpvLknji3ixPiyz2YZCQMXj2FN7hvzbfc2Ig+IzAHO0iiBCH9oWuBDq"/>
+            <anonymous>
+                <quota calls="10" period="PT60S" initial-available-calls="10" max-available-calls="10"/>
+            </anonymous>
+        </users>
+        <groups>
+            <group name="readers">
+                <users>
+                    <anonymous/>
+                </users>
+                <roles>
+                    <reader/>
+                </roles>
+            </group>
+            <group name="writers">
+                <users>
+                    <user ref="woggioni"/>
+                    <user ref="gitea"/>
+                </users>
+                <roles>
+                    <reader/>
+                    <writer/>
+                </roles>
+            </group>
+        </groups>
+    </authorization>
+    <authentication>
+        <none/>
+    </authentication>
+</rbcs:server>
--- a/rbcs-cli/native-image/native-image.properties
+++ b/rbcs-cli/native-image/native-image.properties
@@ -1,2 +1,2 @@
-Args=-O3 --gc=serial --install-exit-handlers --initialize-at-run-time=io.netty --enable-url-protocols=jpms --initialize-at-build-time=net.woggioni.rbcs.common.RbcsUrlStreamHandlerFactory,net.woggioni.rbcs.common.RbcsUrlStreamHandlerFactory$JpmsHandler
+Args=-O3 -march=skylake --gc=serial --install-exit-handlers --initialize-at-run-time=io.netty --enable-url-protocols=jpms --initialize-at-build-time=net.woggioni.rbcs.common.RbcsUrlStreamHandlerFactory,net.woggioni.rbcs.common.RbcsUrlStreamHandlerFactory$JpmsHandler
 #-H:TraceClassInitialization=io.netty.handler.ssl.BouncyCastleAlpnSslUtils
--- a/rbcs-cli/native-image/resource-config.json
+++ b/rbcs-cli/native-image/resource-config.json
@@ -1,74 +1,48 @@
 {
-  "resources": {
-    "includes": [
-      {
-        "pattern": "\\QMETA-INF/MANIFEST.MF\\E"
-      },
-      {
-        "pattern": "\\QMETA-INF/services/ch.qos.logback.classic.spi.Configurator\\E"
-      },
-      {
-        "pattern": "\\QMETA-INF/services/java.lang.System$LoggerFinder\\E"
-      },
-      {
-        "pattern": "\\QMETA-INF/services/java.net.spi.InetAddressResolverProvider\\E"
-      },
-      {
-        "pattern": "\\QMETA-INF/services/java.net.spi.URLStreamHandlerProvider\\E"
-      },
-      {
-        "pattern": "\\QMETA-INF/services/java.nio.channels.spi.SelectorProvider\\E"
-      },
-      {
-        "pattern": "\\QMETA-INF/services/java.time.zone.ZoneRulesProvider\\E"
-      },
-      {
-        "pattern": "\\QMETA-INF/services/javax.xml.parsers.DocumentBuilderFactory\\E"
-      },
-      {
-        "pattern": "\\QMETA-INF/services/javax.xml.parsers.SAXParserFactory\\E"
-      },
-      {
-        "pattern": "\\QMETA-INF/services/net.woggioni.rbcs.api.CacheProvider\\E"
-      },
-      {
-        "pattern": "\\QMETA-INF/services/org.slf4j.spi.SLF4JServiceProvider\\E"
-      },
-      {
-        "pattern": "\\Qclasspath:net/woggioni/rbcs/cli/logback.xml\\E"
-      },
-      {
-        "pattern": "\\Qlogback-test.scmo\\E"
-      },
-      {
-        "pattern": "\\Qlogback.scmo\\E"
-      },
-      {
-        "pattern": "\\Qnet/woggioni/rbcs/cli/logback.xml\\E"
-      },
-      {
-        "pattern": "\\Qnet/woggioni/rbcs/server/rbcs-default.xml\\E"
-      },
-      {
-        "pattern": "\\Qnet/woggioni/rbcs/server/schema/rbcs.xsd\\E"
-      },
-      {
-        "pattern": "\\Qnet/woggioni/rbcs/client/schema/rbcs-client.xsd\\E"
-      },
-      {
-        "pattern": "\\Q/net/woggioni/rbcs/server/memcache/schema/rbcs-memcache.xsd\\E"
-      },
-      {
-        "pattern": "java.base:\\Qsun/text/resources/LineBreakIteratorData\\E"
-      }
-    ]
-  },
-  "bundles": [
-    {
-      "name": "com.sun.org.apache.xerces.internal.impl.xpath.regex.message",
-      "locales": [
-        ""
-      ]
-    }
-  ]
+  "resources":{
+  "includes":[{
+    "pattern":"\\QMETA-INF/MANIFEST.MF\\E"
+  }, {
+    "pattern":"\\QMETA-INF/services/ch.qos.logback.classic.spi.Configurator\\E"
+  }, {
+    "pattern":"\\QMETA-INF/services/java.lang.System$LoggerFinder\\E"
+  }, {
+    "pattern":"\\QMETA-INF/services/java.net.spi.InetAddressResolverProvider\\E"
+  }, {
+    "pattern":"\\QMETA-INF/services/java.net.spi.URLStreamHandlerProvider\\E"
+  }, {
+    "pattern":"\\QMETA-INF/services/java.nio.channels.spi.SelectorProvider\\E"
+  }, {
+    "pattern":"\\QMETA-INF/services/java.time.zone.ZoneRulesProvider\\E"
+  }, {
+    "pattern":"\\QMETA-INF/services/javax.xml.parsers.DocumentBuilderFactory\\E"
+  }, {
+    "pattern":"\\QMETA-INF/services/javax.xml.parsers.SAXParserFactory\\E"
+  }, {
+    "pattern":"\\QMETA-INF/services/net.woggioni.rbcs.api.CacheProvider\\E"
+  }, {
+    "pattern":"\\QMETA-INF/services/org.slf4j.spi.SLF4JServiceProvider\\E"
+  }, {
+    "pattern":"\\Qclasspath:net/woggioni/rbcs/cli/logback.xml\\E"
+  }, {
+    "pattern":"\\Qlogback-test.scmo\\E"
+  }, {
+    "pattern":"\\Qlogback.scmo\\E"
+  }, {
+    "pattern":"\\Qnet/woggioni/rbcs/cli/logback.xml\\E"
+  }, {
+    "pattern":"\\Qnet/woggioni/rbcs/client/schema/rbcs-client.xsd\\E"
+  }, {
+    "pattern":"\\Qnet/woggioni/rbcs/server/rbcs-default.xml\\E"
+  }, {
+    "pattern":"\\Qnet/woggioni/rbcs/server/schema/rbcs-server.xsd\\E"
+  }, {
+    "pattern":"\\Q/net/woggioni/rbcs/server/memcache/schema/rbcs-memcache.xsd\\E"
+  }, {
+    "pattern":"java.base:\\Qsun/text/resources/LineBreakIteratorData\\E"
+  }]},
+  "bundles":[{
+    "name":"com.sun.org.apache.xerces.internal.impl.xpath.regex.message",
+    "locales":[""]
+  }]
 }
--- a/rbcs-cli/native-image/serialization-config.json
+++ b/rbcs-cli/native-image/serialization-config.json
@@ -1,5 +1,8 @@
 {
  "types":[
+    {
+      "name":"java.lang.String"
+    },
    {
      "name":"net.woggioni.rbcs.api.CacheValueMetadata"
    }
--- a/rbcs-cli/src/configureNativeImage/kotlin/net/woggioni/rbcs/cli/graal/GraalNativeImageConfiguration.kt
+++ b/rbcs-cli/src/configureNativeImage/kotlin/net/woggioni/rbcs/cli/graal/GraalNativeImageConfiguration.kt
@@ -1,12 +1,14 @@
 package net.woggioni.rbcs.cli.graal

+import net.woggioni.jwo.NullOutputStream
 import net.woggioni.rbcs.api.Configuration
 import net.woggioni.rbcs.api.Configuration.User
 import net.woggioni.rbcs.api.Role
 import net.woggioni.rbcs.cli.RemoteBuildCacheServerCli
 import net.woggioni.rbcs.cli.impl.commands.BenchmarkCommand
+import net.woggioni.rbcs.cli.impl.commands.GetCommand
 import net.woggioni.rbcs.cli.impl.commands.HealthCheckCommand
-import net.woggioni.rbcs.client.RemoteBuildCacheClient
+import net.woggioni.rbcs.cli.impl.commands.PutCommand
 import net.woggioni.rbcs.common.HostAndPort
 import net.woggioni.rbcs.common.PasswordSecurity.hashPassword
 import net.woggioni.rbcs.common.RBCS
@@ -16,29 +18,34 @@ import net.woggioni.rbcs.server.cache.FileSystemCacheConfiguration
 import net.woggioni.rbcs.server.cache.InMemoryCacheConfiguration
 import net.woggioni.rbcs.server.configuration.Parser
 import net.woggioni.rbcs.server.memcache.MemcacheCacheConfiguration
+import java.io.ByteArrayInputStream
 import java.net.URI
 import java.nio.file.Path
 import java.time.Duration
 import java.time.temporal.ChronoUnit
 import java.util.concurrent.ExecutionException
 import java.util.zip.Deflater
+import net.woggioni.rbcs.client.Configuration as ClientConfiguration
+import net.woggioni.rbcs.client.impl.Parser as ClientConfigurationParser

 object GraalNativeImageConfiguration {
    @JvmStatic
    fun main(vararg args : String) {

-        val serverDoc = RemoteBuildCacheServer.DEFAULT_CONFIGURATION_URL.openStream().use {
-            Xml.parseXml(RemoteBuildCacheServer.DEFAULT_CONFIGURATION_URL, it)
+        val serverURL = URI.create("file:conf/rbcs-client.xml").toURL()
+        val serverDoc = serverURL.openStream().use {
+            Xml.parseXml(serverURL, it)
        }
-        Parser.parse(doc)
+        Parser.parse(serverDoc)

-        val clientDoc = RemoteBuildCacheClient.Configuration.openStream().use {
-            Xml.parseXml(RemoteBuildCacheServer.DEFAULT_CONFIGURATION_URL, it)
+        val url = URI.create("file:conf/rbcs-client.xml").toURL()
+        val clientDoc = url.openStream().use {
+            Xml.parseXml(url, it)
        }
-        Parser.parse(doc)
+        ClientConfigurationParser.parse(clientDoc)

        val PASSWORD = "password"
-        val readersGroup = Configuration.Group("readers", setOf(Role.Reader), null, null)
+        val readersGroup = Configuration.Group("readers", setOf(Role.Reader, Role.Healthcheck), null, null)
        val writersGroup = Configuration.Group("writers", setOf(Role.Writer), null, null)


@@ -126,30 +133,44 @@ object GraalNativeImageConfiguration {
            val serverHandle = RemoteBuildCacheServer(serverConfiguration).run()


-            val clientProfile = RemoteBuildCacheClient.Configuration.Profile(
+            val clientProfile = ClientConfiguration.Profile(
                URI.create("http://127.0.0.1:$serverPort/"),
                null,
-                RemoteBuildCacheClient.Configuration.Authentication.BasicAuthenticationCredentials("user3", PASSWORD),
+                ClientConfiguration.Authentication.BasicAuthenticationCredentials("user3", PASSWORD),
                Duration.ofSeconds(3),
                10,
                true,
-                RemoteBuildCacheClient.Configuration.RetryPolicy(
+                ClientConfiguration.RetryPolicy(
                    3,
                    1000,
                    1.2
                ),
-                RemoteBuildCacheClient.Configuration.TrustStore(null, null, false, false)
+                ClientConfiguration.TrustStore(null, null, false, false)
            )

-            HealthCheckCommand.run(clientProfile)
+            HealthCheckCommand.execute(clientProfile)

-            BenchmarkCommand.run(
+            BenchmarkCommand.execute(
                clientProfile,
                1000,
                0x100,
                true
            )

+            PutCommand.execute(
+                clientProfile,
+                "some-file.bin",
+                ByteArrayInputStream(ByteArray(0x1000) { it.toByte() }),
+                "application/octet-setream",
+                "attachment; filename=\"some-file.bin\""
+            )
+
+            GetCommand.execute(
+                clientProfile,
+                "some-file.bin",
+                NullOutputStream()
+            )
+
            serverHandle.sendShutdownSignal()
            try {
                serverHandle.get()
--- a/rbcs-cli/src/main/kotlin/net/woggioni/rbcs/cli/RemoteBuildCacheServerCli.kt
+++ b/rbcs-cli/src/main/kotlin/net/woggioni/rbcs/cli/RemoteBuildCacheServerCli.kt
@@ -11,7 +11,7 @@ import net.woggioni.rbcs.cli.impl.commands.PasswordHashCommand
 import net.woggioni.rbcs.cli.impl.commands.PutCommand
 import net.woggioni.rbcs.cli.impl.commands.ServerCommand
 import net.woggioni.rbcs.common.RbcsUrlStreamHandlerFactory
-import net.woggioni.rbcs.common.contextLogger
+import net.woggioni.rbcs.common.createLogger
 import picocli.CommandLine
 import picocli.CommandLine.Model.CommandSpec

@@ -36,7 +36,7 @@ class RemoteBuildCacheServerCli : RbcsCommand() {
                //We're running in an envelope jar and custom URL protocols won't work
                RbcsUrlStreamHandlerFactory.install()
            }
-            val log = contextLogger()
+            val log = createLogger<RemoteBuildCacheServerCli>()
            val app = Application.builder("rbcs")
                .configurationDirectoryEnvVar("RBCS_CONFIGURATION_DIR")
                .configurationDirectoryPropertyKey("net.woggioni.rbcs.conf.dir")
--- a/rbcs-cli/src/main/kotlin/net/woggioni/rbcs/cli/impl/commands/BenchmarkCommand.kt
+++ b/rbcs-cli/src/main/kotlin/net/woggioni/rbcs/cli/impl/commands/BenchmarkCommand.kt
@@ -5,6 +5,7 @@ import net.woggioni.jwo.LongMath
 import net.woggioni.rbcs.api.CacheValueMetadata
 import net.woggioni.rbcs.cli.impl.RbcsCommand
 import net.woggioni.rbcs.cli.impl.converters.ByteSizeConverter
+import net.woggioni.rbcs.client.Configuration
 import net.woggioni.rbcs.client.RemoteBuildCacheClient
 import net.woggioni.rbcs.common.createLogger
 import net.woggioni.rbcs.common.debug
@@ -29,7 +30,7 @@ class BenchmarkCommand : RbcsCommand() {
    companion object {
        private val log = createLogger<BenchmarkCommand>()

-        fun run(profile : RemoteBuildCacheClient.Configuration.Profile,
+        fun execute(profile : Configuration.Profile,
                    numberOfEntries : Int,
                    entrySize : Int,
                    useRandomValue : Boolean,
@@ -175,7 +176,7 @@ class BenchmarkCommand : RbcsCommand() {
            clientCommand.configuration.profiles[profileName]
                ?: throw IllegalArgumentException("Profile $profileName does not exist in configuration")
        }
-        run(
+        execute(
            profile,
            numberOfEntries,
            size,
--- a/rbcs-cli/src/main/kotlin/net/woggioni/rbcs/cli/impl/commands/ClientCommand.kt
+++ b/rbcs-cli/src/main/kotlin/net/woggioni/rbcs/cli/impl/commands/ClientCommand.kt
@@ -2,8 +2,11 @@ package net.woggioni.rbcs.cli.impl.commands

 import net.woggioni.jwo.Application
 import net.woggioni.rbcs.cli.impl.RbcsCommand
-import net.woggioni.rbcs.client.RemoteBuildCacheClient
+import net.woggioni.rbcs.client.Configuration
+import net.woggioni.rbcs.common.createLogger
+import net.woggioni.rbcs.common.debug
 import picocli.CommandLine
+import java.lang.IllegalArgumentException
 import java.nio.file.Path

@CommandLine.Command(
@@ -24,15 +27,20 @@ class ClientCommand(app : Application) : RbcsCommand() {
        names = ["-p", "--profile"],
        description = ["Name of the client profile to be used"],
        paramLabel = "PROFILE",
-        required = true
+        required = false
    )
    var profileName : String? = null
+        get() = field ?: throw IllegalArgumentException("A profile name must be specified using the '-p' command line parameter")

-    val configuration : RemoteBuildCacheClient.Configuration by lazy {
-        RemoteBuildCacheClient.Configuration.parse(configurationFile)
+    val configuration : Configuration by lazy {
+        Configuration.parse(configurationFile)
    }

    override fun run() {
+        val log = createLogger<ClientCommand>()
+        log.debug {
+            "Using configuration file '$configurationFile'"
+        }
        println("Available profiles:")
        configuration.profiles.forEach { (profileName, _) ->
            println(profileName)
--- a/rbcs-cli/src/main/kotlin/net/woggioni/rbcs/cli/impl/commands/GetCommand.kt
+++ b/rbcs-cli/src/main/kotlin/net/woggioni/rbcs/cli/impl/commands/GetCommand.kt
@@ -1,9 +1,11 @@
 package net.woggioni.rbcs.cli.impl.commands

 import net.woggioni.rbcs.cli.impl.RbcsCommand
+import net.woggioni.rbcs.client.Configuration
 import net.woggioni.rbcs.client.RemoteBuildCacheClient
 import net.woggioni.rbcs.common.createLogger
 import picocli.CommandLine
+import java.io.OutputStream
 import java.nio.file.Files
 import java.nio.file.Path

@@ -13,8 +15,20 @@ import java.nio.file.Path
    showDefaultValues = true
 )
 class GetCommand : RbcsCommand() {
-    companion object{
+    companion object {
        private val log = createLogger<GetCommand>()
+
+        fun execute(profile : Configuration.Profile, key : String, outputStream: OutputStream) {
+            RemoteBuildCacheClient(profile).use { client ->
+                client.get(key).thenApply { value ->
+                    value?.let {
+                        outputStream.use {
+                            it.write(value)
+                        }
+                    } ?: throw NoSuchElementException("No value found for key $key")
+                }.get()
+            }
+        }
    }

    @CommandLine.Spec
@@ -40,14 +54,6 @@ class GetCommand : RbcsCommand() {
            clientCommand.configuration.profiles[profileName]
                ?: throw IllegalArgumentException("Profile $profileName does not exist in configuration")
        }
-        RemoteBuildCacheClient(profile).use { client ->
-            client.get(key).thenApply { value ->
-                value?.let {
-                    (output?.let(Files::newOutputStream) ?: System.out).use {
-                        it.write(value)
-                    }
-                } ?: throw NoSuchElementException("No value found for key $key")
-            }.get()
-        }
+        execute(profile, key, (output?.let(Files::newOutputStream) ?: System.out))
    }
 }
--- a/rbcs-cli/src/main/kotlin/net/woggioni/rbcs/cli/impl/commands/HealthCheckCommand.kt
+++ b/rbcs-cli/src/main/kotlin/net/woggioni/rbcs/cli/impl/commands/HealthCheckCommand.kt
@@ -1,6 +1,7 @@
 package net.woggioni.rbcs.cli.impl.commands

 import net.woggioni.rbcs.cli.impl.RbcsCommand
+import net.woggioni.rbcs.client.Configuration
 import net.woggioni.rbcs.client.RemoteBuildCacheClient
 import net.woggioni.rbcs.common.createLogger
 import picocli.CommandLine
@@ -16,7 +17,7 @@ class HealthCheckCommand : RbcsCommand() {
    companion object{
        private val log = createLogger<HealthCheckCommand>()

-        fun run(profile : RemoteBuildCacheClient.Configuration.Profile) {
+        fun execute(profile : Configuration.Profile) {
            RemoteBuildCacheClient(profile).use { client ->
                val random = Random(SecureRandom.getInstance("NativePRNGNonBlocking").nextLong())
                val nonce = ByteArray(0xa0)
@@ -47,6 +48,6 @@ class HealthCheckCommand : RbcsCommand() {
            clientCommand.configuration.profiles[profileName]
                ?: throw IllegalArgumentException("Profile $profileName does not exist in configuration")
        }
-        run(profile)
+        execute(profile)
    }
 }
--- a/rbcs-cli/src/main/kotlin/net/woggioni/rbcs/cli/impl/commands/PutCommand.kt
+++ b/rbcs-cli/src/main/kotlin/net/woggioni/rbcs/cli/impl/commands/PutCommand.kt
@@ -5,6 +5,7 @@ import net.woggioni.jwo.JWO
 import net.woggioni.jwo.NullOutputStream
 import net.woggioni.rbcs.api.CacheValueMetadata
 import net.woggioni.rbcs.cli.impl.RbcsCommand
+import net.woggioni.rbcs.client.Configuration
 import net.woggioni.rbcs.client.RemoteBuildCacheClient
 import net.woggioni.rbcs.common.createLogger
 import picocli.CommandLine
@@ -19,8 +20,22 @@ import java.util.UUID
    showDefaultValues = true
 )
 class PutCommand : RbcsCommand() {
-    companion object{
+    companion object {
        private val log = createLogger<PutCommand>()
+
+        fun execute(profile: Configuration.Profile,
+                    actualKey : String,
+                    inputStream: InputStream,
+                    mimeType : String?,
+                    contentDisposition: String?
+        ) {
+            RemoteBuildCacheClient(profile).use { client ->
+                inputStream.use {
+                    client.put(actualKey, it.readAllBytes(), CacheValueMetadata(contentDisposition, mimeType))
+                }.get()
+                println(profile.serverURI.resolve(actualKey))
+            }
+        }
    }


@@ -92,10 +107,7 @@ class PutCommand : RbcsCommand() {
                }
                actualKey = key ?: UUID.randomUUID().toString()
            }
-            inputStream.use {
-                client.put(actualKey, it.readAllBytes(), CacheValueMetadata(contentDisposition, mimeType))
-            }.get()
-            println(profile.serverURI.resolve(actualKey))
+            execute(profile, actualKey, inputStream, mimeType, contentDisposition)
        }
    }
 }
--- a/rbcs-client/src/main/kotlin/net/woggioni/rbcs/client/Configuration.kt
+++ b/rbcs-client/src/main/kotlin/net/woggioni/rbcs/client/Configuration.kt
@@ -0,0 +1,61 @@
+package net.woggioni.rbcs.client
+
+import net.woggioni.rbcs.client.impl.Parser
+import net.woggioni.rbcs.common.Xml
+import java.net.URI
+import java.nio.file.Files
+import java.nio.file.Path
+import java.security.PrivateKey
+import java.security.cert.X509Certificate
+import java.time.Duration
+
+data class Configuration(
+    val profiles: Map<String, Profile>
+) {
+    sealed class Authentication {
+        data class TlsClientAuthenticationCredentials(
+            val key: PrivateKey,
+            val certificateChain: Array<X509Certificate>
+        ) : Authentication()
+
+        data class BasicAuthenticationCredentials(val username: String, val password: String) : Authentication()
+    }
+
+    class TrustStore (
+        var file: Path?,
+        var password: String?,
+        var checkCertificateStatus: Boolean = false,
+        var verifyServerCertificate: Boolean = true,
+    )
+
+    class RetryPolicy(
+        val maxAttempts: Int,
+        val initialDelayMillis: Long,
+        val exp: Double
+    )
+
+    class Connection(
+        val readIdleTimeout: Duration,
+        val writeIdleTimeout: Duration,
+        val idleTimeout: Duration,
+    )
+
+    data class Profile(
+        val serverURI: URI,
+        val connection: Connection?,
+        val authentication: Authentication?,
+        val connectionTimeout: Duration?,
+        val maxConnections: Int,
+        val compressionEnabled: Boolean,
+        val retryPolicy: RetryPolicy?,
+        val tlsTruststore : TrustStore?
+    )
+
+    companion object {
+        fun parse(path: Path): Configuration {
+            return Files.newInputStream(path).use {
+                Xml.parseXml(path.toUri().toURL(), it)
+            }.let(Parser::parse)
+        }
+    }
+}
--- a/rbcs-client/src/main/kotlin/net/woggioni/rbcs/client/RemoteBuildCacheClient.kt
+++ b/rbcs-client/src/main/kotlin/net/woggioni/rbcs/client/RemoteBuildCacheClient.kt
@@ -36,20 +36,14 @@ import io.netty.handler.timeout.IdleStateHandler
 import io.netty.util.concurrent.Future
 import io.netty.util.concurrent.GenericFutureListener
 import net.woggioni.rbcs.api.CacheValueMetadata
-import net.woggioni.rbcs.client.impl.Parser
 import net.woggioni.rbcs.common.RBCS.loadKeystore
-import net.woggioni.rbcs.common.Xml
 import net.woggioni.rbcs.common.createLogger
 import net.woggioni.rbcs.common.debug
 import net.woggioni.rbcs.common.trace
 import java.io.IOException
 import java.net.InetSocketAddress
 import java.net.URI
-import java.nio.file.Files
-import java.nio.file.Path
-import java.security.PrivateKey
 import java.security.cert.X509Certificate
-import java.time.Duration
 import java.util.Base64
 import java.util.concurrent.CompletableFuture
 import java.util.concurrent.TimeUnit
@@ -69,59 +63,6 @@ class RemoteBuildCacheClient(private val profile: Configuration.Profile) : AutoC
    private val sslContext: SslContext
    private val pool: ChannelPool

-    data class Configuration(
-        val profiles: Map<String, Profile>
-    ) {
-        sealed class Authentication {
-            data class TlsClientAuthenticationCredentials(
-                val key: PrivateKey,
-                val certificateChain: Array<X509Certificate>
-            ) : Authentication()
-
-            data class BasicAuthenticationCredentials(val username: String, val password: String) : Authentication()
-        }
-
-        class TrustStore (
-            var file: Path?,
-            var password: String?,
-            var checkCertificateStatus: Boolean = false,
-            var verifyServerCertificate: Boolean = true,
-        )
-
-        class RetryPolicy(
-            val maxAttempts: Int,
-            val initialDelayMillis: Long,
-            val exp: Double
-        )
-
-        class Connection(
-            val readTimeout: Duration,
-            val writeTimeout: Duration,
-            val idleTimeout: Duration,
-            val readIdleTimeout: Duration,
-            val writeIdleTimeout: Duration
-        )
-
-        data class Profile(
-            val serverURI: URI,
-            val connection: Connection?,
-            val authentication: Authentication?,
-            val connectionTimeout: Duration?,
-            val maxConnections: Int,
-            val compressionEnabled: Boolean,
-            val retryPolicy: RetryPolicy?,
-            val tlsTruststore : TrustStore?
-        )
-
-        companion object {
-            fun parse(path: Path): Configuration {
-                return Files.newInputStream(path).use {
-                    Xml.parseXml(path.toUri().toURL(), it)
-                }.let(Parser::parse)
-            }
-        }
-    }
-
    init {
        group = NioEventLoopGroup()
        sslContext = SslContextBuilder.forClient().also { builder ->
@@ -212,19 +153,6 @@ class RemoteBuildCacheClient(private val profile: Configuration.Profile) : AutoC
                val pipeline: ChannelPipeline = ch.pipeline()

                profile.connection?.also { conn ->
-                    val readTimeout = conn.readTimeout.toMillis()
-                    val writeTimeout = conn.writeTimeout.toMillis()
-                    if (readTimeout > 0 || writeTimeout > 0) {
-                        pipeline.addLast(
-                            IdleStateHandler(
-                                false,
-                                readTimeout,
-                                writeTimeout,
-                                0,
-                                TimeUnit.MILLISECONDS
-                            )
-                        )
-                    }
                    val readIdleTimeout = conn.readIdleTimeout.toMillis()
                    val writeIdleTimeout = conn.writeIdleTimeout.toMillis()
                    val idleTimeout = conn.idleTimeout.toMillis()
--- a/rbcs-client/src/main/kotlin/net/woggioni/rbcs/client/impl/Parser.kt
+++ b/rbcs-client/src/main/kotlin/net/woggioni/rbcs/client/impl/Parser.kt
@@ -1,7 +1,7 @@
 package net.woggioni.rbcs.client.impl

 import net.woggioni.rbcs.api.exception.ConfigurationException
-import net.woggioni.rbcs.client.RemoteBuildCacheClient
+import net.woggioni.rbcs.client.Configuration
 import net.woggioni.rbcs.common.Xml.Companion.asIterable
 import net.woggioni.rbcs.common.Xml.Companion.renderAttribute
 import org.w3c.dom.Document
@@ -16,9 +16,9 @@ import java.time.temporal.ChronoUnit

 object Parser {

-    fun parse(document: Document): RemoteBuildCacheClient.Configuration {
+    fun parse(document: Document): Configuration {
        val root = document.documentElement
-        val profiles = mutableMapOf<String, RemoteBuildCacheClient.Configuration.Profile>()
+        val profiles = mutableMapOf<String, Configuration.Profile>()

        for (child in root.asIterable()) {
            val tagName = child.localName
@@ -28,10 +28,10 @@ object Parser {
                        child.renderAttribute("name") ?: throw ConfigurationException("name attribute is required")
                    val uri = child.renderAttribute("base-url")?.let(::URI)
                        ?: throw ConfigurationException("base-url attribute is required")
-                    var authentication: RemoteBuildCacheClient.Configuration.Authentication? = null
-                    var retryPolicy: RemoteBuildCacheClient.Configuration.RetryPolicy? = null
-                    var connection : RemoteBuildCacheClient.Configuration.Connection? = null
-                    var trustStore : RemoteBuildCacheClient.Configuration.TrustStore? = null
+                    var authentication: Configuration.Authentication? = null
+                    var retryPolicy: Configuration.RetryPolicy? = null
+                    var connection : Configuration.Connection? = null
+                    var trustStore : Configuration.TrustStore? = null
                    for (gchild in child.asIterable()) {
                        when (gchild.localName) {
                            "tls-client-auth" -> {
@@ -52,7 +52,7 @@ object Parser {
                                    .toList()
                                    .toTypedArray()
                                authentication =
-                                    RemoteBuildCacheClient.Configuration.Authentication.TlsClientAuthenticationCredentials(
+                                    Configuration.Authentication.TlsClientAuthenticationCredentials(
                                        key,
                                        certChain
                                    )
@@ -64,7 +64,7 @@ object Parser {
                                val password = gchild.renderAttribute("password")
                                    ?: throw ConfigurationException("password attribute is required")
                                authentication =
-                                    RemoteBuildCacheClient.Configuration.Authentication.BasicAuthenticationCredentials(
+                                    Configuration.Authentication.BasicAuthenticationCredentials(
                                        username,
                                        password
                                    )
@@ -83,7 +83,7 @@ object Parser {
                                    gchild.renderAttribute("exp")
                                        ?.let(String::toDouble)
                                        ?: 2.0f
-                                retryPolicy = RemoteBuildCacheClient.Configuration.RetryPolicy(
+                                retryPolicy = Configuration.RetryPolicy(
                                    maxAttempts,
                                    initialDelay.toMillis(),
                                    exp.toDouble()
@@ -91,22 +91,16 @@ object Parser {
                            }

                            "connection" -> {
-                                val writeTimeout = gchild.renderAttribute("write-timeout")
-                                    ?.let(Duration::parse) ?: Duration.of(0, ChronoUnit.SECONDS)
-                                val readTimeout = gchild.renderAttribute("read-timeout")
-                                    ?.let(Duration::parse) ?: Duration.of(0, ChronoUnit.SECONDS)
                                val idleTimeout = gchild.renderAttribute("idle-timeout")
                                    ?.let(Duration::parse) ?: Duration.of(30, ChronoUnit.SECONDS)
                                val readIdleTimeout = gchild.renderAttribute("read-idle-timeout")
                                    ?.let(Duration::parse) ?: Duration.of(60, ChronoUnit.SECONDS)
                                val writeIdleTimeout = gchild.renderAttribute("write-idle-timeout")
                                    ?.let(Duration::parse) ?: Duration.of(60, ChronoUnit.SECONDS)
-                                connection = RemoteBuildCacheClient.Configuration.Connection(
-                                    readTimeout,
-                                    writeTimeout,
-                                    idleTimeout,
+                                connection = Configuration.Connection(
                                    readIdleTimeout,
                                    writeIdleTimeout,
+                                    idleTimeout,
                                )
                            }

@@ -118,7 +112,7 @@ object Parser {
                                    ?.let(String::toBoolean) ?: false
                                val verifyServerCertificate = gchild.renderAttribute("verify-server-certificate")
                                    ?.let(String::toBoolean) ?: true
-                                trustStore = RemoteBuildCacheClient.Configuration.TrustStore(file, password, checkCertificateStatus, verifyServerCertificate)
+                                trustStore = Configuration.TrustStore(file, password, checkCertificateStatus, verifyServerCertificate)
                            }
                        }
                    }
@@ -131,7 +125,7 @@ object Parser {
                        ?.let(String::toBoolean)
                        ?: true

-                    profiles[name] = RemoteBuildCacheClient.Configuration.Profile(
+                    profiles[name] = Configuration.Profile(
                        uri,
                        connection,
                        authentication,
@@ -144,6 +138,6 @@ object Parser {
                }
            }
        }
-        return RemoteBuildCacheClient.Configuration(profiles)
+        return Configuration(profiles)
    }
 }
--- a/rbcs-client/src/main/resources/net/woggioni/rbcs/client/schema/rbcs-client.xsd
+++ b/rbcs-client/src/main/resources/net/woggioni/rbcs/client/schema/rbcs-client.xsd
@@ -15,75 +15,237 @@
    <xs:complexType name="profileType">
        <xs:sequence>
            <xs:choice>
-                <xs:element name="no-auth" type="rbcs-client:noAuthType"/>
-                <xs:element name="basic-auth" type="rbcs-client:basicAuthType"/>
-                <xs:element name="tls-client-auth" type="rbcs-client:tlsClientAuthType"/>
+                <xs:element name="no-auth" type="rbcs-client:noAuthType">
+                    <xs:annotation>
+                        <xs:documentation>
+                            Disable authentication.
+                        </xs:documentation>
+                    </xs:annotation>
+                </xs:element>
+                <xs:element name="basic-auth" type="rbcs-client:basicAuthType">
+                    <xs:annotation>
+                        <xs:documentation>
+                            Enable HTTP basic authentication.
+                        </xs:documentation>
+                    </xs:annotation>
+                </xs:element>
+                <xs:element name="tls-client-auth" type="rbcs-client:tlsClientAuthType">
+                    <xs:annotation>
+                        <xs:documentation>
+                            Enable TLS certificate authentication.
+                        </xs:documentation>
+                    </xs:annotation>
+                </xs:element>
            </xs:choice>
-            <xs:element name="connection" type="rbcs-client:connectionType" minOccurs="0" />
-            <xs:element name="retry-policy" type="rbcs-client:retryType" minOccurs="0"/>
-            <xs:element name="tls-trust-store" type="rbcs-client:trustStoreType" minOccurs="0"/>
+            <xs:element name="connection" type="rbcs-client:connectionType" minOccurs="0" >
+                <xs:annotation>
+                    <xs:documentation>
+                        Set inactivity timeouts for connections to this server,
+                        if not present, connections are only closed on network errors.
+                    </xs:documentation>
+                </xs:annotation>
+            </xs:element>
+            <xs:element name="retry-policy" type="rbcs-client:retryType" minOccurs="0">
+                <xs:annotation>
+                    <xs:documentation>
+                        Set a retry policy for this server, if not present requests won't be retried
+                    </xs:documentation>
+                </xs:annotation>
+            </xs:element>
+            <xs:element name="tls-trust-store" type="rbcs-client:trustStoreType" minOccurs="0">
+                <xs:annotation>
+                    <xs:documentation>
+                        If set, specify an alternative truststore to validate the server certificate.
+                        If not present the system truststore is used.
+                    </xs:documentation>
+                </xs:annotation>
+            </xs:element>
        </xs:sequence>
-        <xs:attribute name="name" type="xs:token" use="required"/>
-        <xs:attribute name="base-url" type="xs:anyURI" use="required"/>
-        <xs:attribute name="max-connections" type="xs:positiveInteger" default="50"/>
-        <xs:attribute name="connection-timeout" type="xs:duration"/>
-        <xs:attribute name="enable-compression" type="xs:boolean" default="true"/>
+        <xs:attribute name="name" type="xs:token" use="required">
+            <xs:annotation>
+                <xs:documentation>
+                    Name of this server profile, to be referred to from rbcs-cli with the '-p' parameter
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
+        <xs:attribute name="base-url" type="xs:anyURI" use="required">
+            <xs:annotation>
+                <xs:documentation>
+                    RBCs server URL
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
+        <xs:attribute name="max-connections" type="xs:positiveInteger" default="50">
+            <xs:annotation>
+                <xs:documentation>
+                    Maximum number of concurrent TCP connection to open with this server
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
+        <xs:attribute name="connection-timeout" type="xs:duration">
+            <xs:annotation>
+                <xs:documentation>
+                    Enable HTTP compression when communicating to this server
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
+        <xs:attribute name="enable-compression" type="xs:boolean" default="true">
+            <xs:annotation>
+                <xs:documentation>
+                    Enable HTTP compression when communicating to this server
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
    </xs:complexType>

    <xs:complexType name="connectionType">
-        <xs:attribute name="read-timeout" type="xs:duration" use="optional" default="PT0S"/>
-        <xs:attribute name="write-timeout" type="xs:duration" use="optional" default="PT0S"/>
-        <xs:attribute name="idle-timeout" type="xs:duration" use="optional" default="PT30S"/>
-        <xs:attribute name="read-idle-timeout" type="xs:duration" use="optional" default="PT60S"/>
-        <xs:attribute name="write-idle-timeout" type="xs:duration" use="optional" default="PT60S"/>
+        <xs:attribute name="idle-timeout" type="xs:duration" use="optional" default="PT30S">
+            <xs:annotation>
+                <xs:documentation>
+                    The client will close the connection with the server
+                    when neither a read nor a write was performed for the specified period of time.
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
+        <xs:attribute name="read-idle-timeout" type="xs:duration" use="optional" default="PT60S">
+            <xs:annotation>
+                <xs:documentation>
+                    The client will close the connection with the server
+                    when no read was performed for the specified period of time.
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
+        <xs:attribute name="write-idle-timeout" type="xs:duration" use="optional" default="PT60S">
+            <xs:annotation>
+                <xs:documentation>
+                    The client will close the connection with the server
+                    when no write was performed for the specified period of time.
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
    </xs:complexType>

-    <xs:complexType name="noAuthType"/>
+    <xs:complexType name="noAuthType">
+        <xs:annotation>
+            <xs:documentation>
+                Add this tag to not use any type of authentication when talking to the RBCS server
+            </xs:documentation>
+        </xs:annotation>
+    </xs:complexType>

    <xs:complexType name="basicAuthType">
-        <xs:attribute name="user" type="xs:token" use="required"/>
-        <xs:attribute name="password" type="xs:string" use="required"/>
+        <xs:annotation>
+            <xs:documentation>
+                Add this tag to enable HTTP basic authentication for the communication to this server,
+                mind that HTTP basic authentication sends credentials directly over the network, so make sure
+                your communication is protected by TLS (i.e. your server's URL starts with "https")
+            </xs:documentation>
+        </xs:annotation>
+        <xs:attribute name="user" type="xs:token" use="required">
+            <xs:annotation>
+                <xs:documentation>
+                    Username for HTTP basic authentication
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
+        <xs:attribute name="password" type="xs:string" use="required">
+            <xs:annotation>
+                <xs:documentation>
+                    Password used for HTTP basic authentication
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
    </xs:complexType>

    <xs:complexType name="tlsClientAuthType">
-        <xs:attribute name="key-store-file" type="xs:anyURI" use="required"/>
-        <xs:attribute name="key-store-password" type="xs:string" use="required"/>
-        <xs:attribute name="key-alias" type="xs:token" use="required"/>
-        <xs:attribute name="key-password" type="xs:string" use="optional"/>
+        <xs:attribute name="key-store-file" type="xs:anyURI" use="required">
+            <xs:annotation>
+                <xs:documentation>
+                    System path to the keystore file
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
+        <xs:attribute name="key-store-password" type="xs:string" use="required">
+            <xs:annotation>
+                <xs:documentation>
+                    Password to open they keystore file
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
+        <xs:attribute name="key-alias" type="xs:token" use="required">
+            <xs:annotation>
+                <xs:documentation>
+                    Alias of the keystore entry containing the private key
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
+        <xs:attribute name="key-password" type="xs:string" use="optional">
+            <xs:annotation>
+                <xs:documentation>
+                    Private key entry's encryption password
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
    </xs:complexType>

    <xs:complexType name="retryType">
-        <xs:attribute name="max-attempts" type="xs:positiveInteger" use="required"/>
-        <xs:attribute name="initial-delay" type="xs:duration" default="PT1S"/>
-        <xs:attribute name="exp" type="xs:double" default="2.0"/>
+        <xs:annotation>
+            <xs:documentation>
+                Retry policy to use in case of failures, based on exponential backoff
+                https://en.wikipedia.org/wiki/Exponential_backoff
+            </xs:documentation>
+        </xs:annotation>
+
+        <xs:attribute name="max-attempts" type="xs:positiveInteger" use="required">
+            <xs:annotation>
+                <xs:documentation>
+                    Maximum number of attempts, after which the call will result in an error,
+                    throwing an exception related to the last received failure
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
+        <xs:attribute name="initial-delay" type="xs:duration" default="PT1S">
+            <xs:annotation>
+                <xs:documentation>
+                    Delay to apply before retrying after the first failed call
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
+        <xs:attribute name="exp" type="xs:double" default="2.0">
+            <xs:annotation>
+                <xs:documentation>
+                    Exponent to apply to compute the next delay
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
    </xs:complexType>

    <xs:complexType name="trustStoreType">
        <xs:attribute name="file" type="xs:string" use="required">
            <xs:annotation>
                <xs:documentation>
-                    Path to the trustore file
+                    Path to the truststore file
                </xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name="password" type="xs:string">
            <xs:annotation>
                <xs:documentation>
-                    Trustore file password
+                    Truststore file password
                </xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name="check-certificate-status" type="xs:boolean">
            <xs:annotation>
                <xs:documentation>
-                    Whether or not check the certificate validity using CRL/OCSP
+                    Whether or not check the server certificate validity using CRL/OCSP
                </xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name="verify-server-certificate" type="xs:boolean" use="optional" default="true">
            <xs:annotation>
                <xs:documentation>
-                    If false, the client will blindly trust the provided server certificate
+                    If false, the client will blindly trust the certificate provided by the server
                </xs:documentation>
            </xs:annotation>
        </xs:attribute>
--- a/rbcs-client/src/test/kotlin/net/woggioni/rbcs/client/RetryTest.kt
+++ b/rbcs-client/src/test/kotlin/net/woggioni/rbcs/client/RetryTest.kt
@@ -129,7 +129,7 @@ class RetryTest {
                    previousAttempt.first + testArgs.initialDelay * Math.pow(testArgs.exp, index.toDouble()) * 1e6
                val actualTimestamp = timestamp
                val err = Math.abs(expectedTimestamp - actualTimestamp) / expectedTimestamp
-                Assertions.assertTrue(err < 1e-2)
+                Assertions.assertTrue(err < 0.1)
            }
            if (index == attempts.size - 1 && index < testArgs.maxAttempt - 1) {
                /*
--- a/rbcs-server-memcache/README.md
+++ b/rbcs-server-memcache/README.md
@@ -30,7 +30,7 @@ The plugins currently supports the following configuration attributes:
 <rbcs:server xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:rbcs="urn:net.woggioni.rbcs.server"
             xmlns:rbcs-memcache="urn:net.woggioni.rbcs.server.memcache"
-             xs:schemaLocation="urn:net.woggioni.rbcs.server.memcache jpms://net.woggioni.rbcs.server.memcache/net/woggioni/rbcs/server/memcache/schema/rbcs-memcache.xsd urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs.xsd"
+             xs:schemaLocation="urn:net.woggioni.rbcs.server.memcache jpms://net.woggioni.rbcs.server.memcache/net/woggioni/rbcs/server/memcache/schema/rbcs-memcache.xsd urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd"
 >
    ...
    <cache xs:type="rbcs-memcache:memcacheCacheType" 
--- a/rbcs-server-memcache/src/main/resources/net/woggioni/rbcs/server/memcache/schema/rbcs-memcache.xsd
+++ b/rbcs-server-memcache/src/main/resources/net/woggioni/rbcs/server/memcache/schema/rbcs-memcache.xsd
@@ -4,7 +4,7 @@
           xmlns:rbcs="urn:net.woggioni.rbcs.server"
           xmlns:xs="http://www.w3.org/2001/XMLSchema">

-    <xs:import schemaLocation="jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs.xsd" namespace="urn:net.woggioni.rbcs.server"/>
+    <xs:import schemaLocation="jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd" namespace="urn:net.woggioni.rbcs.server"/>

    <xs:complexType name="memcacheServerType">
        <xs:attribute name="host" type="xs:token" use="required"/>
--- a/rbcs-server/src/main/kotlin/net/woggioni/rbcs/server/auth/UserAuthorizer.kt
+++ b/rbcs-server/src/main/kotlin/net/woggioni/rbcs/server/auth/UserAuthorizer.kt
@@ -8,8 +8,9 @@ class RoleAuthorizer : Authorizer {

    companion object {
        private val METHOD_MAP = mapOf(
-            Role.Reader to setOf(HttpMethod.GET, HttpMethod.HEAD, HttpMethod.TRACE),
-            Role.Writer to setOf(HttpMethod.PUT, HttpMethod.POST)
+            Role.Reader to setOf(HttpMethod.GET, HttpMethod.HEAD),
+            Role.Writer to setOf(HttpMethod.PUT, HttpMethod.POST),
+            Role.Healthcheck to setOf(HttpMethod.TRACE)
        )
    }

--- a/rbcs-server/src/main/kotlin/net/woggioni/rbcs/server/cache/FileSystemCacheProvider.kt
+++ b/rbcs-server/src/main/kotlin/net/woggioni/rbcs/server/cache/FileSystemCacheProvider.kt
@@ -12,7 +12,7 @@ import java.util.zip.Deflater

 class FileSystemCacheProvider : CacheProvider<FileSystemCacheConfiguration> {

-    override fun getXmlSchemaLocation() = "classpath:net/woggioni/rbcs/server/schema/rbcs.xsd"
+    override fun getXmlSchemaLocation() = "classpath:net/woggioni/rbcs/server/schema/rbcs-server.xsd"

    override fun getXmlType() = "fileSystemCacheType"

--- a/rbcs-server/src/main/kotlin/net/woggioni/rbcs/server/cache/InMemoryCacheProvider.kt
+++ b/rbcs-server/src/main/kotlin/net/woggioni/rbcs/server/cache/InMemoryCacheProvider.kt
@@ -11,7 +11,7 @@ import java.util.zip.Deflater

 class InMemoryCacheProvider : CacheProvider<InMemoryCacheConfiguration> {

-    override fun getXmlSchemaLocation() = "classpath:net/woggioni/rbcs/server/schema/rbcs.xsd"
+    override fun getXmlSchemaLocation() = "classpath:net/woggioni/rbcs/server/schema/rbcs-server.xsd"

    override fun getXmlType() = "inMemoryCacheType"

--- a/rbcs-server/src/main/kotlin/net/woggioni/rbcs/server/configuration/Parser.kt
+++ b/rbcs-server/src/main/kotlin/net/woggioni/rbcs/server/configuration/Parser.kt
@@ -193,6 +193,7 @@ object Parser {
        when (it.localName) {
            "reader" -> Role.Reader
            "writer" -> Role.Writer
+            "healthcheck" -> Role.Healthcheck
            else -> throw UnsupportedOperationException("Illegal node '${it.localName}'")
        }
    }.toSet()
--- a/rbcs-server/src/main/resources/net/woggioni/rbcs/server/rbcs-default.xml
+++ b/rbcs-server/src/main/resources/net/woggioni/rbcs/server/rbcs-default.xml
@@ -2,7 +2,7 @@
 <rbcs:server
             xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:rbcs="urn:net.woggioni.rbcs.server"
-             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs.xsd">
+             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd">
    <bind host="127.0.0.1" port="8080" incoming-connections-backlog-size="1024"/>
    <cache xs:type="rbcs:fileSystemCacheType" path="${sys:java.io.tmpdir}/rbcs" max-age="P7D"/>
 </rbcs:server>
--- a/rbcs-server/src/main/resources/net/woggioni/rbcs/server/schema/rbcs-server.xsd
+++ b/rbcs-server/src/main/resources/net/woggioni/rbcs/server/schema/rbcs-server.xsd
@@ -424,7 +424,8 @@
        <xs:attribute name="password" type="xs:string" use="optional">
            <xs:annotation>
                <xs:documentation>
-                    User's password used in HTTP basic authentication
+                    User's password hash used for HTTP basic authentication, this has to be generated with
+                    the `password` subcommand of `rbcs-cli`
                </xs:documentation>
            </xs:annotation>
        </xs:attribute>
@@ -498,18 +499,12 @@
        </xs:attribute>
    </xs:complexType>

-    <xs:simpleType name="role" final="restriction" >
-        <xs:restriction base="xs:token">
-            <xs:enumeration value="READER" />
-            <xs:enumeration value="WRITER" />
-        </xs:restriction>
-    </xs:simpleType>
-
    <xs:complexType name="rolesType">
        <xs:sequence>
            <xs:choice maxOccurs="unbounded">
                <xs:element name="writer"/>
                <xs:element name="reader"/>
+                <xs:element name="healthcheck"/>
            </xs:choice>
        </xs:sequence>
    </xs:complexType>
--- a/rbcs-server/src/test/kotlin/net/woggioni/rbcs/server/test/AbstractTlsServerTest.kt
+++ b/rbcs-server/src/test/kotlin/net/woggioni/rbcs/server/test/AbstractTlsServerTest.kt
@@ -47,6 +47,7 @@ abstract class AbstractTlsServerTest : AbstractServerTest() {

    protected val readersGroup = Configuration.Group("readers", setOf(Role.Reader), null, null)
    protected val writersGroup = Configuration.Group("writers", setOf(Role.Writer), null, null)
+    protected val healthCheckGroup = Configuration.Group("healthcheckers", setOf(Role.Healthcheck), null, null)
    protected val random = Random(101325)
    protected val keyValuePair = newEntry(random)
    private val serverPath : String? = null
--- a/rbcs-server/src/test/kotlin/net/woggioni/rbcs/server/test/TlsServerTest.kt
+++ b/rbcs-server/src/test/kotlin/net/woggioni/rbcs/server/test/TlsServerTest.kt
@@ -18,6 +18,7 @@ class TlsServerTest : AbstractTlsServerTest() {
        Configuration.User("user1", null, setOf(readersGroup), null),
        Configuration.User("user2", null, setOf(writersGroup), null),
        Configuration.User("user3", null, setOf(readersGroup, writersGroup), null),
+        Configuration.User("user4", null, setOf(healthCheckGroup), null),
        Configuration.User("", null, setOf(readersGroup), null)
    )

@@ -140,7 +141,24 @@ class TlsServerTest : AbstractTlsServerTest() {
        val client: HttpClient = getHttpClient(null)
        val requestBuilder = newRequestBuilder("").method(
            "TRACE",
-            HttpRequest.BodyPublishers.ofByteArray("sfgsdgfaiousfiuhsd".toByteArray())
+            HttpRequest.BodyPublishers.ofByteArray("this is an healthcheck".toByteArray())
+        )
+
+        val response: HttpResponse<ByteArray> =
+            client.send(requestBuilder.build(), HttpResponse.BodyHandlers.ofByteArray())
+        Assertions.assertEquals(HttpResponseStatus.FORBIDDEN.code(), response.statusCode())
+    }
+
+    @Test
+    @Order(9)
+    fun traceAsHealthcheckUser() {
+        val user = cfg.users.values.find {
+            Role.Healthcheck in it.roles
+        } ?: throw RuntimeException("Reader user not found")
+        val client: HttpClient = getHttpClient(getClientKeyStore(ca, X500Name("CN=${user.name}")))
+        val requestBuilder = newRequestBuilder("").method(
+            "TRACE",
+            HttpRequest.BodyPublishers.ofByteArray("this is an healthcheck".toByteArray())
        )

        val response: HttpResponse<ByteArray> =
--- a/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/invalid/duplicate-anonymous-user.xml
+++ b/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/invalid/duplicate-anonymous-user.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <rbcs:server xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:rbcs="urn:net.woggioni.rbcs.server"
-             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs.xsd">
+             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd">
    <bind host="127.0.0.1" port="11443"/>
    <cache xs:type="rbcs:fileSystemCacheType" path="/tmp/rbcs" max-age="P7D"/>
    <authorization>
--- a/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/invalid/duplicate-anonymous-user2.xml
+++ b/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/invalid/duplicate-anonymous-user2.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <rbcs:server xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:rbcs="urn:net.woggioni.rbcs.server"
-             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs.xsd">
+             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd">
    <bind host="127.0.0.1" port="11443"/>
    <cache xs:type="rbcs:fileSystemCacheType" path="/tmp/rbcs" max-age="P7D"/>
    <authorization>
--- a/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/invalid/invalid-user-ref.xml
+++ b/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/invalid/invalid-user-ref.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <rbcs:server xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:rbcs="urn:net.woggioni.rbcs.server"
-             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs.xsd">
+             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd">
    <bind host="127.0.0.1" port="11443"/>
    <cache xs:type="rbcs:fileSystemCacheType" path="/tmp/rbcs" max-age="P7D"/>
    <authorization>
--- a/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/invalid/multiple-user-quota.xml
+++ b/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/invalid/multiple-user-quota.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <rbcs:server xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:rbcs="urn:net.woggioni.rbcs.server"
-             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs.xsd">
+             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd">
    <bind host="127.0.0.1" port="11443"/>
    <cache xs:type="rbcs:fileSystemCacheType" path="/tmp/rbcs" max-age="P7D"/>
    <authorization>
--- a/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/valid/rbcs-default.xml
+++ b/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/valid/rbcs-default.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <rbcs:server xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:rbcs="urn:net.woggioni.rbcs.server"
-             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs.xsd">
+             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd">
    <bind host="127.0.0.1" port="11443" incoming-connections-backlog-size="22"/>
    <connection
            read-idle-timeout="PT10M"
--- a/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/valid/rbcs-memcached-tls.xml
+++ b/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/valid/rbcs-memcached-tls.xml
@@ -2,7 +2,7 @@
 <rbcs:server xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:rbcs="urn:net.woggioni.rbcs.server"
             xmlns:rbcs-memcache="urn:net.woggioni.rbcs.server.memcache"
-             xs:schemaLocation="urn:net.woggioni.rbcs.server.memcache jpms://net.woggioni.rbcs.server.memcache/net/woggioni/rbcs/server/memcache/schema/rbcs-memcache.xsd urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs.xsd"
+             xs:schemaLocation="urn:net.woggioni.rbcs.server.memcache jpms://net.woggioni.rbcs.server.memcache/net/woggioni/rbcs/server/memcache/schema/rbcs-memcache.xsd urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd"
 >
    <bind host="0.0.0.0" port="8443" incoming-connections-backlog-size="4096"/>
    <connection
--- a/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/valid/rbcs-memcached.xml
+++ b/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/valid/rbcs-memcached.xml
@@ -2,7 +2,7 @@
 <rbcs:server xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:rbcs="urn:net.woggioni.rbcs.server"
             xmlns:rbcs-memcache="urn:net.woggioni.rbcs.server.memcache"
-             xs:schemaLocation="urn:net.woggioni.rbcs.server.memcache jpms://net.woggioni.rbcs.server.memcache/net/woggioni/rbcs/server/memcache/schema/rbcs-memcache.xsd urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs.xsd">
+             xs:schemaLocation="urn:net.woggioni.rbcs.server.memcache jpms://net.woggioni.rbcs.server.memcache/net/woggioni/rbcs/server/memcache/schema/rbcs-memcache.xsd urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd">
    <bind host="127.0.0.1" port="11443" incoming-connections-backlog-size="50"/>
    <connection
            read-idle-timeout="PT10M"
--- a/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/valid/rbcs-tls.xml
+++ b/rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/valid/rbcs-tls.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <rbcs:server xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:rbcs="urn:net.woggioni.rbcs.server"
-             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs.xsd">
+             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd">
    <bind host="127.0.0.1" port="11443" incoming-connections-backlog-size="180"/>
    <connection
            read-idle-timeout="PT10M"
--- a/rbcs-servlet/README.md
+++ b/rbcs-servlet/README.md
@@ -1,3 +1,10 @@
+# RBCS servlet
+
+This is a minimal implementation of RBCs using Jakarta servlet API, it relies
+on the servlet container (Tomcat in this example) for authentication, authorization,
+throttling, encryption and compression. It only supports in-memory caching.
+The main purpose is to provide a performance comparison for RBCS Netty implementation.
+
 ## How to run

 ```bash
Author	SHA1	Message	Date
Walter Oggioni	d15235fc4c	fixed missing plugin in native image All checks were successful CI / build (push) Successful in 34m59s Details	2025-02-27 23:30:33 +08:00
Walter Oggioni	49bb4f41b8	improved documentation	2025-02-26 21:40:58 +08:00
Walter Oggioni	a1398045ac	fixed native image configuration task All checks were successful CI / build (push) Successful in 37m16s Details	2025-02-26 17:42:02 +08:00
Walter Oggioni	1f93602102	added healthcheck role improved documentation client configuration promoted to standalone class	2025-02-26 15:26:18 +08:00
Walter Oggioni	c818463a2e	fixed entrypoint in native Docker image	2025-02-25 22:26:29 +08:00
Walter Oggioni	cd28563985	fixed typo	2025-02-25 22:06:52 +08:00
Walter Oggioni	8ef2d9c64e	improved usability of `native` docker image All checks were successful CI / build (push) Successful in 33m19s Details	2025-02-25 21:31:02 +08:00
Walter Oggioni	1510956989	update JWO version to fix bug All checks were successful CI / build (push) Successful in 34m13s Details the `RBCS_CONFIGURATION_DIR` was ignored because of a bug in JWO	2025-02-25 20:10:09 +08:00
Walter Oggioni	ac4f0fdd19	increased tolerance of RetryTest	2025-02-25 19:19:07 +08:00