From bcc6f257112b6f660a000e87e2b0c4164aade4a2 Mon Sep 17 00:00:00 2001
From: Xin Zheng <xin.zheng@post.ch>
Date: Fri, 4 Oct 2024 10:46:43 +0700
Subject: [PATCH 01/10] S3 supports

---
 pom.xml                                       |  13 +-
 .../swisspush/reststorage/RestStorageMod.java |  14 +-
 .../reststorage/s3/FileReadStream.java        | 272 ++++++++++++++
 .../reststorage/s3/FileWriteStream.java       | 111 ++++++
 .../reststorage/s3/S3FileSystemDirLister.java | 135 +++++++
 .../reststorage/s3/S3FileSystemStorage.java   | 355 ++++++++++++++++++
 .../reststorage/util/ModuleConfiguration.java |  42 ++-
 7 files changed, 938 insertions(+), 4 deletions(-)
 create mode 100644 src/main/java/org/swisspush/reststorage/s3/FileReadStream.java
 create mode 100644 src/main/java/org/swisspush/reststorage/s3/FileWriteStream.java
 create mode 100644 src/main/java/org/swisspush/reststorage/s3/S3FileSystemDirLister.java
 create mode 100644 src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java

diff --git a/pom.xml b/pom.xml
index 7b543d4..9c3a451 100644
--- a/pom.xml
+++ b/pom.xml
@@ -69,7 +69,11 @@
             <artifactId>guava</artifactId>
             <version>${guava.version}</version>
         </dependency>
-
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>s3</artifactId>
+            <version>${awssdk.version}</version>
+        </dependency>
         <!-- TEST dependencies -->
         <dependency>
             <!--
@@ -133,6 +137,11 @@
             <artifactId>jackson-databind</artifactId>
             <version>${jackson.version}</version>
         </dependency>
+        <dependency>
+            <groupId>software.amazon.nio.s3</groupId>
+            <artifactId>aws-java-nio-spi-for-s3</artifactId>
+            <version>${nio.spi.s3.version}</version>
+        </dependency>
     </dependencies>
     <build>
         <pluginManagement>
@@ -404,6 +413,8 @@
     </profiles>
     <properties>
         <vertx.version>4.5.2</vertx.version>
+        <awssdk.version>2.27.17</awssdk.version>
+        <nio.spi.s3.version>2.1.0</nio.spi.s3.version>
         <slf4j.version>2.0.10</slf4j.version>
         <junit.version>4.13.2</junit.version>
         <jackson.version>2.16.0</jackson.version>
diff --git a/src/main/java/org/swisspush/reststorage/RestStorageMod.java b/src/main/java/org/swisspush/reststorage/RestStorageMod.java
index fccfb73..d038e82 100644
--- a/src/main/java/org/swisspush/reststorage/RestStorageMod.java
+++ b/src/main/java/org/swisspush/reststorage/RestStorageMod.java
@@ -1,6 +1,10 @@
 package org.swisspush.reststorage;
-
-import io.vertx.core.*;
+;
+import io.vertx.core.AbstractVerticle;
+import io.vertx.core.Future;
+import io.vertx.core.Handler;
+import io.vertx.core.Promise;
+import io.vertx.core.Vertx;
 import io.vertx.core.http.HttpServerOptions;
 import io.vertx.core.http.HttpServerRequest;
 import org.slf4j.Logger;
@@ -9,6 +13,7 @@
 import org.swisspush.reststorage.redis.DefaultRedisProvider;
 import org.swisspush.reststorage.redis.RedisProvider;
 import org.swisspush.reststorage.redis.RedisStorage;
+import org.swisspush.reststorage.s3.S3FileSystemStorage;
 import org.swisspush.reststorage.util.ModuleConfiguration;
 
 import static org.swisspush.reststorage.exception.RestStorageExceptionFactory.newRestStorageThriftyExceptionFactory;
@@ -73,6 +78,11 @@ private Future<Storage> createStorage(ModuleConfiguration moduleConfiguration) {
             case filesystem:
                 promise.complete(new FileSystemStorage(vertx, exceptionFactory, moduleConfiguration.getRoot()));
                 break;
+            case s3:
+                promise.complete(new S3FileSystemStorage(vertx, exceptionFactory, moduleConfiguration.getRoot(),
+                        moduleConfiguration.getAwsS3Region(), moduleConfiguration.getAwsS3BucketName(),
+                        moduleConfiguration.getAwsS3AccessKeyId(), moduleConfiguration.getAwsS3SecretAccessKey()));
+                break;
             case redis:
                 createRedisStorage(vertx, moduleConfiguration).onComplete(event -> {
                     if(event.succeeded()){
diff --git a/src/main/java/org/swisspush/reststorage/s3/FileReadStream.java b/src/main/java/org/swisspush/reststorage/s3/FileReadStream.java
new file mode 100644
index 0000000..00eab0c
--- /dev/null
+++ b/src/main/java/org/swisspush/reststorage/s3/FileReadStream.java
@@ -0,0 +1,272 @@
+package org.swisspush.reststorage.s3;
+
+import io.vertx.core.AsyncResult;
+import io.vertx.core.Context;
+import io.vertx.core.Future;
+import io.vertx.core.Handler;
+import io.vertx.core.Vertx;
+import io.vertx.core.buffer.Buffer;
+import io.vertx.core.streams.ReadStream;
+import io.vertx.core.streams.impl.InboundBuffer;
+import org.slf4j.Logger;
+
+import java.io.Closeable;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.ByteBuffer;
+import java.nio.channels.Channels;
+import java.nio.channels.ReadableByteChannel;
+
+import static io.vertx.core.file.impl.AsyncFileImpl.DEFAULT_READ_BUFFER_SIZE;
+import static org.slf4j.LoggerFactory.getLogger;
+
+
+public class FileReadStream<T> implements ReadStream<T>, Closeable {
+
+    private static final Logger log = getLogger(FileReadStream.class);
+    private final long expectedSize;
+    private final String path;
+
+    private final ReadableByteChannel ch;
+    private final Vertx vertx;
+    private final Context context;
+
+    private boolean closed;
+    private boolean readInProgress;
+
+    private Handler<Buffer> dataHandler;
+    private Handler<Void> endHandler;
+    private Handler<Throwable> exceptionHandler;
+    private final InboundBuffer<Buffer> queue;
+
+    private int readBufferSize = DEFAULT_READ_BUFFER_SIZE;
+    private long writtenBytes = 0;
+
+    /**
+     * @param expectedSize Actual file size which is expected to be streamed through that stream
+     *                     in bytes.
+     * @param path         Token printed alongside the logs so when reading logs, we can see which
+     *                     log belongs to which file. A possible candidate is to use the file path
+     *                     but it theoretically can be anything  which  helps  you  to  find  logs
+     *                     related to your observed file.
+     * @param stream       The file (or stream) we wanna observe.
+     */
+    public FileReadStream(Vertx vertx, long expectedSize, String path, InputStream stream) {
+        this.vertx = vertx;
+        this.context = vertx.getOrCreateContext();
+        this.expectedSize = expectedSize;
+        this.path = path;
+        this.ch = Channels.newChannel(stream);
+        this.queue = new InboundBuffer<>(context, 0);
+        queue.handler(buff -> {
+            if (buff.length() > 0) {
+                handleData(buff);
+            } else {
+                handleEnd();
+            }
+        });
+        queue.drainHandler(v -> {
+            doRead();
+        });
+    }
+
+    public void close() {
+        closeInternal(null);
+    }
+
+    public void close(Handler<AsyncResult<Void>> handler) {
+        closeInternal(handler);
+    }
+
+    @Override
+    public ReadStream<T> exceptionHandler(Handler<Throwable> exceptionHandler) {
+        log.trace("exceptionHandler registered for reading '{}'", path);
+        check();
+        this.exceptionHandler = exceptionHandler;
+        return this;
+    }
+
+    @Override
+    public ReadStream<T> handler(Handler handler) {
+        log.trace("handler registered");
+        check();
+        this.dataHandler = handler;
+        if (this.dataHandler != null && !this.closed) {
+            this.doRead();
+        } else {
+            queue.clear();
+        }
+        return this;
+    }
+
+    @Override
+    public ReadStream<T> pause() {
+        log.debug("Pause reading at offset {} for '{}'", writtenBytes, path);
+        check();
+        queue.pause();
+        return this;
+    }
+
+    @Override
+    public ReadStream<T> resume() {
+        log.debug("Resume reading at offset {} for '{}'", writtenBytes, path);
+        check();
+        if (!closed) {
+            queue.resume();
+        }
+        return this;
+    }
+
+    @Override
+    public ReadStream<T> fetch(long amount) {
+        log.debug("fetch amount {}", amount);
+        queue.fetch(amount);
+        return this;
+    }
+
+    @Override
+    public ReadStream<T> endHandler(Handler<Void> endHandler) {
+        log.trace("endHandler registered.");
+        check();
+        this.endHandler = endHandler;
+        log.debug("End handler called ({} bytes remaining) for '{}'", expectedSize - writtenBytes, path);
+        return this;
+    }
+
+    private void doRead() {
+        check();
+        doRead(ByteBuffer.allocate(readBufferSize));
+    }
+
+    private synchronized void doRead(ByteBuffer bb) {
+        if (!readInProgress) {
+            readInProgress = true;
+            Buffer buff = Buffer.buffer(readBufferSize);
+            doRead(buff, 0, bb, writtenBytes, ar -> {
+                if (ar.succeeded()) {
+                    readInProgress = false;
+                    Buffer buffer = ar.result();
+                    writtenBytes += buffer.length();
+                    // Empty buffer represents end of file
+                    if (queue.write(buffer) && buffer.length() > 0) {
+                        doRead(bb);
+                    }
+                } else {
+                    handleException(ar.cause());
+                }
+            });
+        }
+    }
+
+    private void doRead(Buffer writeBuff, int offset, ByteBuffer buff, long position, Handler<AsyncResult<Buffer>> handler) {
+
+        // ReadableByteChannel doesn't have a completion handler, so we wrap it into
+        // an executeBlocking and use the future there
+        vertx.executeBlocking(future -> {
+            try {
+                Integer bytesRead = ch.read(buff);
+                future.complete(bytesRead);
+            } catch (Exception e) {
+                log.error("", e);
+                future.fail(e);
+            }
+
+        }, res -> {
+
+            if (res.failed()) {
+                context.runOnContext((v) -> handler.handle(Future.failedFuture(res.cause())));
+            } else {
+                // Do the completed check
+                Integer bytesRead = (Integer) res.result();
+                if (bytesRead == -1) {
+                    //End of file
+                    context.runOnContext((v) -> {
+                        buff.flip();
+                        writeBuff.setBytes(offset, buff);
+                        buff.compact();
+                        handler.handle(Future.succeededFuture(writeBuff));
+                    });
+                } else if (buff.hasRemaining()) {
+                    long pos = position;
+                    pos += bytesRead;
+                    // resubmit
+                    doRead(writeBuff, offset, buff, pos, handler);
+                } else {
+                    // It's been fully written
+
+                    context.runOnContext((v) -> {
+                        buff.flip();
+                        writeBuff.setBytes(offset, buff);
+                        buff.compact();
+                        handler.handle(Future.succeededFuture(writeBuff));
+                    });
+                }
+            }
+        });
+    }
+
+    private void handleData(Buffer buff) {
+        Handler<Buffer> handler;
+        synchronized (this) {
+            handler = this.dataHandler;
+        }
+        if (handler != null) {
+            checkContext();
+            handler.handle(buff);
+        }
+    }
+
+    private synchronized void handleEnd() {
+        Handler<Void> endHandler;
+        synchronized (this) {
+            dataHandler = null;
+            endHandler = this.endHandler;
+        }
+        if (endHandler != null) {
+            checkContext();
+            endHandler.handle(null);
+        }
+    }
+
+    private void handleException(Throwable t) {
+        if (exceptionHandler != null && t instanceof Exception) {
+            exceptionHandler.handle(t);
+        } else {
+            log.error("Unhandled exception", t);
+
+        }
+    }
+
+    private void check() {
+        if (this.closed) {
+            throw new IllegalStateException("Inputstream is closed");
+        }
+    }
+
+    private void checkContext() {
+        if (!vertx.getOrCreateContext().equals(context)) {
+            throw new IllegalStateException("AsyncInputStream must only be used in the context that created it, expected: " + this.context
+                    + " actual " + vertx.getOrCreateContext());
+        }
+    }
+
+    private synchronized void closeInternal(Handler<AsyncResult<Void>> handler) {
+        check();
+        closed = true;
+        doClose(handler);
+    }
+
+    private void doClose(Handler<AsyncResult<Void>> handler) {
+
+        try {
+            ch.close();
+            if (handler != null) {
+                this.vertx.runOnContext(v -> handler.handle(Future.succeededFuture()));
+            }
+        } catch (IOException e) {
+            if (handler != null) {
+                this.vertx.runOnContext(v -> handler.handle(Future.failedFuture(e)));
+            }
+        }
+    }
+}
diff --git a/src/main/java/org/swisspush/reststorage/s3/FileWriteStream.java b/src/main/java/org/swisspush/reststorage/s3/FileWriteStream.java
new file mode 100644
index 0000000..0ffc87a
--- /dev/null
+++ b/src/main/java/org/swisspush/reststorage/s3/FileWriteStream.java
@@ -0,0 +1,111 @@
+package org.swisspush.reststorage.s3;
+
+import io.vertx.core.AsyncResult;
+import io.vertx.core.Future;
+import io.vertx.core.Handler;
+import io.vertx.core.Promise;
+import io.vertx.core.buffer.Buffer;
+import io.vertx.core.streams.WriteStream;
+
+import java.io.OutputStream;
+import java.io.IOException;
+
+public class FileWriteStream implements WriteStream<Buffer> {
+    private final OutputStream outputStream;
+    private Handler<Throwable> exceptionHandler;
+    private Handler<Void> drainHandler;
+    private boolean writeQueueFull = false;
+    private int maxQueueSize = 1024;  // Default max queue size, can be modified
+
+    public FileWriteStream(OutputStream outputStream) {
+        this.outputStream = outputStream;
+    }
+
+    @Override
+    public WriteStream<Buffer> exceptionHandler(Handler<Throwable> handler) {
+        this.exceptionHandler = handler;
+        return this;
+    }
+
+    @Override
+    public void write(Buffer buffer, Handler<AsyncResult<Void>> handler) {
+        try {
+            outputStream.write(buffer.getBytes());
+            outputStream.flush();
+            handler.handle(Future.succeededFuture());
+        } catch (IOException e) {
+            if (exceptionHandler != null) {
+                exceptionHandler.handle(e);
+            }
+            handler.handle(Future.failedFuture(e));
+        }
+    }
+
+    @Override
+    public Future<Void> write(Buffer buffer) {
+        Promise<Void> promise = Promise.promise();
+        try {
+            outputStream.write(buffer.getBytes());
+            outputStream.flush();
+            promise.complete();
+        } catch (IOException e) {
+            if (exceptionHandler != null) {
+                exceptionHandler.handle(e);
+            } else {
+                throw new RuntimeException("Error writing to OutputStream", e);
+            }
+            promise.fail(e);
+        }
+        return promise.future();
+    }
+
+    @Override
+    public void end(Handler<AsyncResult<Void>> handler) {
+        try {
+            outputStream.flush();
+            outputStream.close();
+            handler.handle(Future.succeededFuture());
+        } catch (IOException e) {
+            if (exceptionHandler != null) {
+                exceptionHandler.handle(e);
+            }
+            handler.handle(Future.failedFuture(e));
+        }
+    }
+
+    @Override
+    public Future<Void> end() {
+        Promise<Void> promise = Promise.promise();
+        try {
+            outputStream.flush();
+            outputStream.close();
+            promise.complete();
+        } catch (IOException e) {
+            if (exceptionHandler != null) {
+                exceptionHandler.handle(e);
+            } else {
+                throw new RuntimeException("Error closing OutputStream", e);
+            }
+            promise.fail(e);
+        }
+        return promise.future();
+    }
+
+    @Override
+    public WriteStream<Buffer> setWriteQueueMaxSize(int maxSize) {
+        this.maxQueueSize = maxSize;
+        return this;
+    }
+
+    @Override
+    public boolean writeQueueFull() {
+        // Implement custom logic to manage queue size if needed
+        return writeQueueFull;
+    }
+
+    @Override
+    public WriteStream<Buffer> drainHandler(Handler<Void> handler) {
+        this.drainHandler = handler;
+        return this;
+    }
+}
diff --git a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemDirLister.java b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemDirLister.java
new file mode 100644
index 0000000..edc9ef4
--- /dev/null
+++ b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemDirLister.java
@@ -0,0 +1,135 @@
+package org.swisspush.reststorage.s3;
+
+import io.vertx.core.Handler;
+import io.vertx.core.Promise;
+import io.vertx.core.Vertx;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.swisspush.reststorage.CollectionResource;
+import org.swisspush.reststorage.DocumentResource;
+import org.swisspush.reststorage.Resource;
+import software.amazon.nio.spi.s3.S3FileSystem;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.stream.Stream;
+
+import static org.swisspush.reststorage.s3.S3FileSystemStorage.S3_PATH_SEPARATOR;
+
+
+/**
+ * This type handles listing of directories in S3.
+ *
+ * <p>Internally it makes use of worker-threads to keep eventloop-thread
+ * responsive.</p>
+ */
+public class S3FileSystemDirLister {
+
+    private static final Logger log = LoggerFactory.getLogger(S3FileSystemDirLister.class);
+    private final Vertx vertx;
+    private final String root;
+    private final S3FileSystem fileSystem;
+
+    public S3FileSystemDirLister(Vertx vertx, S3FileSystem fileSystem, String root) {
+        this.vertx = vertx;
+        this.root = root;
+        this.fileSystem = fileSystem;
+    }
+
+    public void handleListingRequest(Path path, final int offset, final int count, final Handler<Resource> handler) {
+        // Delegate work to worker thread from thread pool.
+        log.trace("Delegate to worker pool");
+        final long startTimeMillis = System.currentTimeMillis();
+        vertx.executeBlocking(promise -> {
+            log.trace("Welcome on worker-thread.");
+            listDirBlocking(path, offset, count, (Promise<CollectionResource>) (Promise<?>) promise);
+            log.trace("worker-thread says bye.");
+        }, event -> {
+            log.trace("Welcome back on eventloop-thread.");
+            if (log.isDebugEnabled()) {
+                final long durationMillis = System.currentTimeMillis() - startTimeMillis;
+                log.debug("List directory contents of '{}' took {}ms", path, durationMillis);
+            }
+            if (event.failed()) {
+                log.error("Directory listing failed.", event.cause());
+                final Resource erroneousResource = new Resource() {{
+                    // Set fields according to documentation in Resource class.
+                    name = path.getFileName().toString();
+                    exists = false;
+                    error = rejected = invalid = true;
+                    errorMessage = invalidMessage = event.cause().getMessage();
+                }};
+                handler.handle(erroneousResource);
+            } else {
+                handler.handle((Resource) event.result());
+            }
+        });
+        log.trace("Work delegated.");
+    }
+
+    private void listDirBlocking(Path path, int offset, int count, Promise<CollectionResource> promise) {
+        // Prepare our result.
+        final CollectionResource collection = new CollectionResource() {{
+            items = new ArrayList<>(128);
+        }};
+        try (Stream<Path> source = Files.list(path)) {
+            source.forEach(entry -> {
+                String entryName = entry.getFileName().toString();
+                log.trace("Processing entry '{}'", entryName);
+                // Create resource representing currently processed directory entry.
+                final Resource resource;
+                if (Files.isDirectory(entry)) {
+                    resource = new CollectionResource();
+                    entryName = entryName.replace(S3_PATH_SEPARATOR, "");
+                } else if (Files.isRegularFile(entry)) {
+                    resource = new DocumentResource();
+                } else {
+                    resource = new Resource();
+                    resource.exists = false;
+                }
+                resource.name = entryName;
+                collection.items.add(resource);
+            });
+        } catch (IOException e) {
+            promise.fail(e);
+            return;
+        }
+        Collections.sort(collection.items);
+        // Don't know exactly what we do here now. Seems we check 'limit' for a range request.
+        int n = count;
+        if (n == -1) {
+            n = collection.items.size();
+        }
+        // Don't know exactly what we do here. But it seems we evaluate 'start' of a range request.
+        if (offset > -1) {
+            if (offset >= collection.items.size() || (offset + n) >= collection.items.size() || (offset == 0 && n == -1)) {
+                promise.complete(collection);
+            } else {
+                collection.items = collection.items.subList(offset, offset + n);
+                promise.complete(collection);
+            }
+        } else {
+            // TODO: Resolve future
+            //       Previous implementation did nothing here. Why? Should we do something here?
+            //       See: "https://github.com/hiddenalpha/vertx-rest-storage/blob/v2.5.2/src/main/java/org/swisspush/reststorage/FileSystemStorage.java#L77"
+            log.warn("May we should do something here. I've no idea why old implementation did nothing.");
+        }
+    }
+
+    private String canonicalizeVirtualPath(String path) {
+        return canonicalizeRealPath(root + path);
+    }
+
+    private static String canonicalizeRealPath(String path) {
+        try {
+            return new File(path).getCanonicalPath();
+        } catch (IOException e) {
+            throw new RuntimeException(e);
+        }
+    }
+
+}
diff --git a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
new file mode 100644
index 0000000..c648dca
--- /dev/null
+++ b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
@@ -0,0 +1,355 @@
+package org.swisspush.reststorage.s3;
+
+import io.vertx.core.Handler;
+import io.vertx.core.Vertx;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.swisspush.reststorage.CollectionResource;
+import org.swisspush.reststorage.DocumentResource;
+import org.swisspush.reststorage.Resource;
+import org.swisspush.reststorage.Storage;
+import org.swisspush.reststorage.exception.RestStorageExceptionFactory;
+import org.swisspush.reststorage.util.LockMode;
+import software.amazon.nio.spi.s3.S3FileSystem;
+
+import java.io.File;
+import java.io.FileNotFoundException;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.net.URI;
+import java.nio.file.DirectoryNotEmptyException;
+import java.nio.file.DirectoryStream;
+import java.nio.file.FileSystemException;
+import java.nio.file.FileSystems;
+import java.nio.file.FileVisitResult;
+import java.nio.file.Files;
+import java.nio.file.LinkOption;
+import java.nio.file.NoSuchFileException;
+import java.nio.file.Path;
+import java.nio.file.SimpleFileVisitor;
+import java.nio.file.attribute.BasicFileAttributes;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+
+
+public class S3FileSystemStorage implements Storage {
+
+    private final Path root;
+    private final Vertx vertx;
+    private final RestStorageExceptionFactory exceptionFactory;
+    private final int rootLen;
+    private final S3FileSystemDirLister fileSystemDirLister;
+    private static volatile S3FileSystem fileSystem;
+
+    private final Logger log = LoggerFactory.getLogger(S3FileSystemStorage.class);
+
+    // See: software.amazon.nio.spi.s3.Constants
+    public static final String S3_PATH_SEPARATOR = "/";
+
+    // use only one file system instance
+    private static S3FileSystem getFileSystem(URI uri) {
+        if (fileSystem == null) {
+            synchronized (S3FileSystem.class) {
+                if (fileSystem == null) {
+                    fileSystem = (S3FileSystem) FileSystems.getFileSystem(uri);
+                }
+            }
+        }
+        return fileSystem;
+    }
+
+    public S3FileSystemStorage(Vertx vertx, RestStorageExceptionFactory exceptionFactory, String rootPath,
+                               String awsS3Region, String awsS3BucketName, String awsS3AccessKeyId, String awsS3SecretAccessKey) {
+        this.vertx = vertx;
+        this.exceptionFactory = exceptionFactory;
+        Objects.requireNonNull(awsS3Region, "Region must not be null");
+        Objects.requireNonNull(awsS3BucketName, "BucketName must not be null");
+        Objects.requireNonNull(awsS3AccessKeyId, "AccessKeyId must not be null");
+        Objects.requireNonNull(awsS3SecretAccessKey, "SecretAccessKey must not be null");
+
+        System.setProperty("aws.region",awsS3Region);
+        System.setProperty("aws.accessKeyId", awsS3AccessKeyId);
+        System.setProperty("aws.secretAccessKey", awsS3SecretAccessKey);
+
+        if (!awsS3BucketName.startsWith("s3:") && !awsS3BucketName.startsWith("s3x:")) {
+            awsS3BucketName = "s3://" + awsS3BucketName;
+        }
+
+        var uri = URI.create(awsS3BucketName);
+        fileSystem = getFileSystem(uri);
+        root = fileSystem.getPath(rootPath);
+
+        try (var pathStream = Files.walk(root)) {
+            pathStream.forEach(System.out::println);
+        } catch (IOException e) {
+            throw new RuntimeException(e);
+        }
+
+        this.fileSystemDirLister = new S3FileSystemDirLister(vertx, fileSystem, root.toString());
+        // Unify format for simpler work.
+        String tmpRoot;
+        tmpRoot = root.toString();
+
+        // Cache string length of root without trailing slashes
+        int rootLen;
+        for (rootLen = tmpRoot.length() - 1; tmpRoot.charAt(rootLen) == '/'; --rootLen) ;
+        this.rootLen = rootLen;
+    }
+
+    @Override
+    public Optional<Float> getCurrentMemoryUsage() {
+        throw new UnsupportedOperationException("Method 'getCurrentMemoryUsage' is not yet implemented for the FileSystemStorage");
+    }
+
+    @Override
+    public void get(String path, String etag, final int offset, final int count, final Handler<Resource> handler) {
+        final Path fullDirPath = canonicalize(path, true);
+        final Path fullFilePath = canonicalize(path, false);
+        log.debug("GET {}", path);
+        if (Files.isRegularFile(fullFilePath, LinkOption.NOFOLLOW_LINKS)) {
+            log.debug("Open file '{}' ({})", path, fullFilePath);
+            DocumentResource d = new DocumentResource();
+            try {
+                final InputStream inputStream = Files.newInputStream(fullFilePath);
+                final FileReadStream<io.vertx.core.buffer.Buffer> readStream = new FileReadStream<>(vertx, d.length, path, inputStream);
+                d.length = Files.size(fullFilePath);
+                log.debug("Successfully opened '{}' which is {} bytes in size.", path, d.length);
+                d.readStream = readStream;
+                d.closeHandler = v -> {
+                    log.debug("Resource got closed. Close file now '{}'", path);
+                    readStream.close();
+                    try {
+                        inputStream.close();
+                    } catch (IOException e) {
+                        log.debug("Failed to close input stream", e);
+                    }
+                };
+            } catch (IOException e) {
+                log.warn("Failed to open '{}' for read", path, e);
+                d.error = true;
+                d.errorMessage = e.getMessage();
+            }
+            handler.handle(d);
+            return;
+        }
+
+        if (Files.isDirectory(fullDirPath)) {
+            log.debug("Delegate directory listing of '{}'", path);
+            fileSystemDirLister.handleListingRequest(fullDirPath, offset, count, handler);
+        } else {
+            log.debug("No such file or directory '{}' ({})", path, fullDirPath);
+            Resource r = new Resource();
+            r.exists = false;
+            handler.handle(r);
+        }
+    }
+
+    @Override
+    public void put(String path, String etag, boolean merge, long expire, final Handler<Resource> handler) {
+        put(path, etag, merge, expire, "", LockMode.SILENT, 0, handler);
+    }
+
+    @Override
+    public void put(String path, String etag, boolean merge, long expire, String lockOwner, LockMode lockMode, long lockExpire, Handler<Resource> handler) {
+        final Path fullPath = canonicalize(path, false);
+        if (Files.exists(fullPath, LinkOption.NOFOLLOW_LINKS)) {
+            if (Files.isDirectory(fullPath)) {
+                CollectionResource c = new CollectionResource();
+                handler.handle(c);
+            } else if (Files.isRegularFile(fullPath, LinkOption.NOFOLLOW_LINKS)) {
+                putFile(handler, fullPath);
+            } else {
+                Resource r = new Resource();
+                r.exists = false;
+                handler.handle(r);
+            }
+        } else {
+            if (Files.exists(fullPath)) {
+                putFile(handler, fullPath);
+            } else {
+                try {
+                    Files.createDirectory(fullPath.getParent());
+                    putFile(handler, fullPath);
+                } catch (IOException e) {
+                    log.error("Failed to create directory '{}'", path);
+                }
+            }
+        }
+    }
+
+    @Override
+    public void put(String path, String etag, boolean merge, long expire, String lockOwner, LockMode lockMode, long lockExpire, boolean storeCompressed, Handler<Resource> handler) {
+        if (storeCompressed) {
+            log.warn("PUT with storeCompressed option is not yet implemented in file system storage. Ignoring storeCompressed option value");
+        }
+        put(path, etag, merge, expire, "", LockMode.SILENT, 0, handler);
+    }
+
+    private void putFile(final Handler<Resource> handler, final Path fullPath) {
+        try {
+            // DON"T close it in finally block, async code
+            final OutputStream outputStream = Files.newOutputStream(fullPath);
+            final DocumentResource d = new DocumentResource();
+
+            FileWriteStream fileWriteStream = new FileWriteStream(outputStream);
+            d.writeStream = fileWriteStream;
+            d.closeHandler = event -> {
+                try {
+                    outputStream.close();
+                    fileWriteStream.end();
+                    d.endHandler.handle(null);
+                } catch (IOException e) {
+                    log.error("Failed to close output stream:", e);
+                }
+            };
+            d.addErrorHandler(err -> {
+                log.error("Put file failed:", err);
+                try {
+                    outputStream.close();
+                } catch (IOException e) {
+                    log.error("Failed to close output stream:", e);
+                }
+            });
+            handler.handle(d);
+        } catch (IOException e) {
+            log.error("Failed to put file:", e);
+        }
+    }
+
+    @Override
+    public void delete(String path, String lockOwner, LockMode lockMode, long lockExpire, boolean confirmCollectionDelete,
+                       boolean deleteRecursive, final Handler<Resource> handler) {
+        final Path fullPath = canonicalize(path, false);
+        Resource resource = new Resource();
+        boolean deleteRecursiveInFileSystem = true;
+        if (confirmCollectionDelete && !deleteRecursive) {
+            deleteRecursiveInFileSystem = false;
+        }
+        boolean finalDeleteRecursiveInFileSystem = deleteRecursiveInFileSystem;
+        if (Files.exists(fullPath, LinkOption.NOFOLLOW_LINKS)) {
+            try {
+                deleteRecursive(fullPath, finalDeleteRecursiveInFileSystem);
+                deleteEmptyParentDirs(fullPath.getParent());
+            } catch (IOException e) {
+                if (e.getCause() != null && e.getCause() instanceof DirectoryNotEmptyException) {
+                    resource.error = true;
+                    resource.errorMessage = "directory not empty. Use recursive=true parameter to delete";
+                } else {
+                    resource.exists = false;
+                }
+            }
+            handler.handle(resource);
+        } else {
+            Resource r = new Resource();
+            r.exists = false;
+            handler.handle(r);
+        }
+    }
+
+    /**
+     * Deletes all empty parent directories starting at specified directory.
+     *
+     * @param path Most deep (virtual) directory to start bubbling up deletion of empty
+     *             directories.
+     */
+    private void deleteEmptyParentDirs(Path path) {
+        // Analyze if we reached root.
+        int pathLen;
+        // Evaluate length of current path excluding trailing slashes by searching
+        // last non-slash (backslash of course on windows).
+        for (pathLen = path.toString().length() - 1; path.toString().charAt(pathLen) == File.separatorChar; --pathLen) ;
+        if (rootLen == pathLen) {
+            // We do NOT want to delete our virtual root even it is empty :)
+            log.debug("Stop deletion here to keep virtual root '{}'.", root);
+            return;
+        }
+        log.debug("Delete directory if empty '{}'.", path);
+
+        if (!isDirEmpty(path)) {
+            log.debug("Directory is NOT empty '{}'.", path);
+            return;
+        }
+
+        try {
+            if (Files.deleteIfExists(path)) {
+                // Bubbling up to parent.
+                final Path parentPath = path.getParent();
+                // HINT 1: We go recursive here!
+                // HINT 2: When debugging stack traces keep in mind this recursion occurs
+                //         asynchronous and therefore is not really a recursion :)
+                deleteEmptyParentDirs(parentPath);
+            } else {
+                throw new FileNotFoundException();
+            }
+        } catch (IOException cause) {
+            if (cause instanceof FileSystemException && cause.getCause() instanceof DirectoryNotEmptyException) {
+                // Failed to delete directory because it's not empty. Therefore we must not
+                // delete it at all and we're done now.
+                log.debug("Directory '{}' not empty. Stop bubbling deleting dirs.", path);
+            } else if (cause instanceof FileSystemException && cause.getCause() instanceof NoSuchFileException) {
+                // Somehow a caller requested to delete a directory which seems not to exist.
+                // This should never be the case theoretically. (except maybe some race
+                // conditions?)
+                log.warn("Ignored to delete non-existing dir '{}'.", path);
+            } else {
+                // This case should not happen. At least up to now i've no idea of a valid
+                // scenario for this one.
+                log.error("Unexpected error while deleting empty directories.", cause);
+            }
+        }
+    }
+
+    public Path canonicalize(String path, boolean isDir) {
+        if (path.startsWith(S3_PATH_SEPARATOR)) {
+            path = path.substring(1);
+        }
+
+        if (!path.endsWith(S3_PATH_SEPARATOR) && isDir) {
+            path = path + S3_PATH_SEPARATOR;
+        }
+        return root.resolve(path);
+    }
+
+    private void deleteRecursive(Path path, boolean recursive) throws IOException {
+        if (recursive) {
+            Files.walkFileTree(path, new SimpleFileVisitor<Path>() {
+                public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) throws IOException {
+                    Files.delete(file);
+                    return FileVisitResult.CONTINUE;
+                }
+
+                public FileVisitResult postVisitDirectory(Path dir, IOException e) throws IOException {
+                    if (e == null) {
+                        Files.delete(dir);
+                        return FileVisitResult.CONTINUE;
+                    } else {
+                        throw e;
+                    }
+                }
+            });
+        } else {
+            Files.delete(path);
+        }
+    }
+
+    private boolean isDirEmpty(final Path path) {
+        try (DirectoryStream<Path> dirStream = Files.newDirectoryStream(path)) {
+            return !dirStream.iterator().hasNext();
+        } catch (IOException e) {
+            log.debug("Error to detects is directory empty or not '{}'.", path, e);
+            return false;
+        }
+    }
+
+    @Override
+    public void cleanup(Handler<DocumentResource> handler, String cleanupResourcesAmount) {
+        // nothing to do here
+    }
+
+    @Override
+    public void storageExpand(String path, String etag, List<String> subResources, Handler<Resource> handler) {
+        throw new UnsupportedOperationException("Method 'storageExpand' is not yet implemented for the FileSystemStorage");
+    }
+}
diff --git a/src/main/java/org/swisspush/reststorage/util/ModuleConfiguration.java b/src/main/java/org/swisspush/reststorage/util/ModuleConfiguration.java
index 2e13921..e6f0910 100644
--- a/src/main/java/org/swisspush/reststorage/util/ModuleConfiguration.java
+++ b/src/main/java/org/swisspush/reststorage/util/ModuleConfiguration.java
@@ -21,7 +21,7 @@ public class ModuleConfiguration {
     private static final Logger log = LoggerFactory.getLogger(ModuleConfiguration.class);
 
     public enum StorageType {
-        filesystem, redis
+        filesystem, redis, s3
     }
 
     private String root = ".";
@@ -70,6 +70,10 @@ public enum StorageType {
     private int maxRedisWaitingHandlers = 2048;
     private int maxStorageExpandSubresources = 1000;
 
+    private String awsS3BucketName = null;
+    private String awsS3Region = null;
+    private String awsS3AccessKeyId = null;
+    private String awsS3SecretAccessKey = null;
 
     public ModuleConfiguration root(String root) {
         this.root = root;
@@ -292,6 +296,26 @@ public ModuleConfiguration maxStorageExpandSubresources(int maxStorageExpandSubr
         return this;
     }
 
+    public ModuleConfiguration awsS3Region(String awsS3Region) {
+        this.awsS3Region = awsS3Region;
+        return this;
+    }
+
+    public ModuleConfiguration awsS3BucketName(String awsS3BucketName) {
+        this.awsS3BucketName = awsS3BucketName;
+        return this;
+    }
+
+    public ModuleConfiguration awsS3AccessKeyId(String awsS3AccessKeyId) {
+        this.awsS3AccessKeyId = awsS3AccessKeyId;
+        return this;
+    }
+
+    public ModuleConfiguration awsS3SecretAccessKey(String awsS3SecretAccessKey) {
+        this.awsS3SecretAccessKey = awsS3SecretAccessKey;
+        return this;
+    }
+
     public String getRoot() {
         return root;
     }
@@ -465,6 +489,22 @@ public int getMaxStorageExpandSubresources() {
         return maxStorageExpandSubresources;
     }
 
+    public String getAwsS3Region() {
+        return awsS3Region;
+    }
+
+    public String getAwsS3BucketName() {
+        return awsS3BucketName;
+    }
+
+    public String getAwsS3AccessKeyId() {
+        return awsS3AccessKeyId;
+    }
+
+    public String getAwsS3SecretAccessKey() {
+        return awsS3SecretAccessKey;
+    }
+
     public JsonObject asJsonObject() {
         return JsonObject.mapFrom(this);
     }

From 10886798b6a7c149f1543dec18cbcb54d056fceb Mon Sep 17 00:00:00 2001
From: Xin Zheng <xin.zheng@post.ch>
Date: Wed, 16 Oct 2024 15:40:43 +0700
Subject: [PATCH 02/10] documents and code improves

---
 README.md                                                | 9 ++++++++-
 .../org/swisspush/reststorage/s3/FileWriteStream.java    | 4 ----
 .../swisspush/reststorage/s3/S3FileSystemStorage.java    | 6 +++---
 3 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 6e99821..cceadc7 100644
--- a/README.md
+++ b/README.md
@@ -223,6 +223,10 @@ The following configuration values are available:
 | rejectStorageWriteOnLowMemory           | redis  | false                    | When set to _true_, PUT requests with the x-importance-level header can be rejected when memory gets low                              |
 | freeMemoryCheckIntervalMs               | redis  | 60000                    | The interval in milliseconds to calculate the actual memory usage                                                                     |
 | redisReadyCheckIntervalMs               | redis  | -1                       | The interval in milliseconds to calculate the "ready state" of redis. When value < 1, no "ready state" will be calculated             |
+| awsS3Region                             | aws-s3 |                          | The region of S3 server                                                                                                               |
+| awsS3BucketName                         | aws-s3 |                          | The S3 bucket name                                                                                                                    |
+| awsS3AccessKeyId                        | aws-s3 |                          | The AWS access key Id, signup at https://docs.aws.amazon.com/SetUp/latest/UserGuide/setup-AWSsignup.html                              |
+| awsS3SecretAccessKey                    | aws-s3 |                          | The AWS secret access key                                                                                                             |
 
 ### Configuration util
 
@@ -249,11 +253,14 @@ JsonObject json  = new ModuleConfiguration().asJsonObject();
 ```
 
 ## Storage types
-Currently, there are two storage types supported. File system storage and redis storage.
+Currently, there are thress storage types supported. File system storage, S3 File storage and redis storage.
 
 ### File System Storage
 The data is stored hierarchically on the file system. This is the default storage type when not overridden in the configuration.
 
+### S3 File storage
+The data is stored in a S3 instance.
+
 ### Redis Storage
 The data is stored in a redis database.
 Caution: The redis storage implementation does not currently support streaming. Avoid transferring too big payloads since they will be entirely copied in memory.
diff --git a/src/main/java/org/swisspush/reststorage/s3/FileWriteStream.java b/src/main/java/org/swisspush/reststorage/s3/FileWriteStream.java
index 0ffc87a..cd8d423 100644
--- a/src/main/java/org/swisspush/reststorage/s3/FileWriteStream.java
+++ b/src/main/java/org/swisspush/reststorage/s3/FileWriteStream.java
@@ -51,8 +51,6 @@ public Future<Void> write(Buffer buffer) {
         } catch (IOException e) {
             if (exceptionHandler != null) {
                 exceptionHandler.handle(e);
-            } else {
-                throw new RuntimeException("Error writing to OutputStream", e);
             }
             promise.fail(e);
         }
@@ -83,8 +81,6 @@ public Future<Void> end() {
         } catch (IOException e) {
             if (exceptionHandler != null) {
                 exceptionHandler.handle(e);
-            } else {
-                throw new RuntimeException("Error closing OutputStream", e);
             }
             promise.fail(e);
         }
diff --git a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
index c648dca..4dd126a 100644
--- a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
+++ b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
@@ -100,7 +100,7 @@ public S3FileSystemStorage(Vertx vertx, RestStorageExceptionFactory exceptionFac
 
     @Override
     public Optional<Float> getCurrentMemoryUsage() {
-        throw new UnsupportedOperationException("Method 'getCurrentMemoryUsage' is not yet implemented for the FileSystemStorage");
+        throw new UnsupportedOperationException("Method 'getCurrentMemoryUsage' not supported in S3FileSystemStorage");
     }
 
     @Override
@@ -314,7 +314,7 @@ public Path canonicalize(String path, boolean isDir) {
 
     private void deleteRecursive(Path path, boolean recursive) throws IOException {
         if (recursive) {
-            Files.walkFileTree(path, new SimpleFileVisitor<Path>() {
+            Files.walkFileTree(path, new SimpleFileVisitor<>() {
                 public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) throws IOException {
                     Files.delete(file);
                     return FileVisitResult.CONTINUE;
@@ -350,6 +350,6 @@ public void cleanup(Handler<DocumentResource> handler, String cleanupResourcesAm
 
     @Override
     public void storageExpand(String path, String etag, List<String> subResources, Handler<Resource> handler) {
-        throw new UnsupportedOperationException("Method 'storageExpand' is not yet implemented for the FileSystemStorage");
+        throw new UnsupportedOperationException("Method 'storageExpand' not supported in S3FileSystemStorage");
     }
 }

From ff8c2f909dcad930c42644eca258930ecafe37f8 Mon Sep 17 00:00:00 2001
From: Xin Zheng <xin.zheng@post.ch>
Date: Thu, 17 Oct 2024 12:03:28 +0700
Subject: [PATCH 03/10] error handling and directory and file check improved

---
 .../reststorage/s3/FileReadStream.java        |  8 +-
 .../reststorage/s3/S3FileSystemDirLister.java | 20 +----
 .../reststorage/s3/S3FileSystemStorage.java   | 83 +++++++++++++------
 3 files changed, 64 insertions(+), 47 deletions(-)

diff --git a/src/main/java/org/swisspush/reststorage/s3/FileReadStream.java b/src/main/java/org/swisspush/reststorage/s3/FileReadStream.java
index 00eab0c..1368fb3 100644
--- a/src/main/java/org/swisspush/reststorage/s3/FileReadStream.java
+++ b/src/main/java/org/swisspush/reststorage/s3/FileReadStream.java
@@ -39,7 +39,7 @@ public class FileReadStream<T> implements ReadStream<T>, Closeable {
     private Handler<Throwable> exceptionHandler;
     private final InboundBuffer<Buffer> queue;
 
-    private int readBufferSize = DEFAULT_READ_BUFFER_SIZE;
+    private final int readBufferSize = DEFAULT_READ_BUFFER_SIZE;
     private long writtenBytes = 0;
 
     /**
@@ -159,7 +159,6 @@ private synchronized void doRead(ByteBuffer bb) {
     }
 
     private void doRead(Buffer writeBuff, int offset, ByteBuffer buff, long position, Handler<AsyncResult<Buffer>> handler) {
-
         // ReadableByteChannel doesn't have a completion handler, so we wrap it into
         // an executeBlocking and use the future there
         vertx.executeBlocking(future -> {
@@ -243,6 +242,10 @@ private void check() {
         }
     }
 
+    public boolean isClosed() {
+        return this.closed;
+    }
+
     private void checkContext() {
         if (!vertx.getOrCreateContext().equals(context)) {
             throw new IllegalStateException("AsyncInputStream must only be used in the context that created it, expected: " + this.context
@@ -257,7 +260,6 @@ private synchronized void closeInternal(Handler<AsyncResult<Void>> handler) {
     }
 
     private void doClose(Handler<AsyncResult<Void>> handler) {
-
         try {
             ch.close();
             if (handler != null) {
diff --git a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemDirLister.java b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemDirLister.java
index edc9ef4..b4c4033 100644
--- a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemDirLister.java
+++ b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemDirLister.java
@@ -8,9 +8,7 @@
 import org.swisspush.reststorage.CollectionResource;
 import org.swisspush.reststorage.DocumentResource;
 import org.swisspush.reststorage.Resource;
-import software.amazon.nio.spi.s3.S3FileSystem;
 
-import java.io.File;
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
@@ -32,12 +30,11 @@ public class S3FileSystemDirLister {
     private static final Logger log = LoggerFactory.getLogger(S3FileSystemDirLister.class);
     private final Vertx vertx;
     private final String root;
-    private final S3FileSystem fileSystem;
 
-    public S3FileSystemDirLister(Vertx vertx, S3FileSystem fileSystem, String root) {
+
+    public S3FileSystemDirLister(Vertx vertx, String root) {
         this.vertx = vertx;
         this.root = root;
-        this.fileSystem = fileSystem;
     }
 
     public void handleListingRequest(Path path, final int offset, final int count, final Handler<Resource> handler) {
@@ -119,17 +116,4 @@ private void listDirBlocking(Path path, int offset, int count, Promise<Collectio
             log.warn("May we should do something here. I've no idea why old implementation did nothing.");
         }
     }
-
-    private String canonicalizeVirtualPath(String path) {
-        return canonicalizeRealPath(root + path);
-    }
-
-    private static String canonicalizeRealPath(String path) {
-        try {
-            return new File(path).getCanonicalPath();
-        } catch (IOException e) {
-            throw new RuntimeException(e);
-        }
-    }
-
 }
diff --git a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
index 4dd126a..b124960 100644
--- a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
+++ b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
@@ -87,7 +87,7 @@ public S3FileSystemStorage(Vertx vertx, RestStorageExceptionFactory exceptionFac
             throw new RuntimeException(e);
         }
 
-        this.fileSystemDirLister = new S3FileSystemDirLister(vertx, fileSystem, root.toString());
+        this.fileSystemDirLister = new S3FileSystemDirLister(vertx, root.toString());
         // Unify format for simpler work.
         String tmpRoot;
         tmpRoot = root.toString();
@@ -113,19 +113,30 @@ public void get(String path, String etag, final int offset, final int count, fin
             DocumentResource d = new DocumentResource();
             try {
                 final InputStream inputStream = Files.newInputStream(fullFilePath);
-                final FileReadStream<io.vertx.core.buffer.Buffer> readStream = new FileReadStream<>(vertx, d.length, path, inputStream);
                 d.length = Files.size(fullFilePath);
                 log.debug("Successfully opened '{}' which is {} bytes in size.", path, d.length);
+
+                final FileReadStream<io.vertx.core.buffer.Buffer> readStream = new FileReadStream<>(vertx, d.length, path, inputStream);
                 d.readStream = readStream;
-                d.closeHandler = v -> {
-                    log.debug("Resource got closed. Close file now '{}'", path);
+
+                final Runnable cleanUp = () -> {
+                    if (!readStream.isClosed()){
                     readStream.close();
+                    }
                     try {
                         inputStream.close();
                     } catch (IOException e) {
                         log.debug("Failed to close input stream", e);
                     }
                 };
+                d.closeHandler = v -> {
+                    log.debug("Resource got closed. Close file now '{}'", path);
+                    cleanUp.run();
+                };
+                d.addErrorHandler(event -> {
+                    log.error("Get resource failed.", exceptionFactory.newException("Close file now '" + path + "'", event));
+                    cleanUp.run();
+                });
             } catch (IOException e) {
                 log.warn("Failed to open '{}' for read", path, e);
                 d.error = true;
@@ -195,22 +206,24 @@ private void putFile(final Handler<Resource> handler, final Path fullPath) {
 
             FileWriteStream fileWriteStream = new FileWriteStream(outputStream);
             d.writeStream = fileWriteStream;
-            d.closeHandler = event -> {
+
+            final Runnable cleanUp = () -> {
+
                 try {
                     outputStream.close();
-                    fileWriteStream.end();
-                    d.endHandler.handle(null);
                 } catch (IOException e) {
                     log.error("Failed to close output stream:", e);
                 }
+                fileWriteStream.end();
+            };
+
+            d.closeHandler = event -> {
+                cleanUp.run();
+                d.endHandler.handle(null);
             };
             d.addErrorHandler(err -> {
                 log.error("Put file failed:", err);
-                try {
-                    outputStream.close();
-                } catch (IOException e) {
-                    log.error("Failed to close output stream:", e);
-                }
+                cleanUp.run();
             });
             handler.handle(d);
         } catch (IOException e) {
@@ -221,14 +234,32 @@ private void putFile(final Handler<Resource> handler, final Path fullPath) {
     @Override
     public void delete(String path, String lockOwner, LockMode lockMode, long lockExpire, boolean confirmCollectionDelete,
                        boolean deleteRecursive, final Handler<Resource> handler) {
-        final Path fullPath = canonicalize(path, false);
+
+        // at this stage I don't know what of this path point to
+        final Path fullFilePath = canonicalize(path, false);
+        final Path fullDirPath = canonicalize(path, true);
+
         Resource resource = new Resource();
         boolean deleteRecursiveInFileSystem = true;
         if (confirmCollectionDelete && !deleteRecursive) {
             deleteRecursiveInFileSystem = false;
         }
         boolean finalDeleteRecursiveInFileSystem = deleteRecursiveInFileSystem;
-        if (Files.exists(fullPath, LinkOption.NOFOLLOW_LINKS)) {
+
+        // try to check as a file
+        boolean exists = Files.exists(fullFilePath, LinkOption.NOFOLLOW_LINKS);
+        Path fullPath = fullFilePath;
+
+        if (!exists) {
+            // not exists, maybe is a directory
+            exists = Files.exists(fullDirPath, LinkOption.NOFOLLOW_LINKS);
+            if (exists) {
+                // so it is a directory
+                fullPath = fullDirPath;
+            }
+        }
+
+        if (exists) {
             try {
                 deleteRecursive(fullPath, finalDeleteRecursiveInFileSystem);
                 deleteEmptyParentDirs(fullPath.getParent());
@@ -248,6 +279,16 @@ public void delete(String path, String lockOwner, LockMode lockMode, long lockEx
         }
     }
 
+    @Override
+    public void cleanup(Handler<DocumentResource> handler, String cleanupResourcesAmount) {
+        // nothing to do here
+    }
+
+    @Override
+    public void storageExpand(String path, String etag, List<String> subResources, Handler<Resource> handler) {
+        throw new UnsupportedOperationException("Method 'storageExpand' not supported in S3FileSystemStorage");
+    }
+
     /**
      * Deletes all empty parent directories starting at specified directory.
      *
@@ -296,7 +337,7 @@ private void deleteEmptyParentDirs(Path path) {
             } else {
                 // This case should not happen. At least up to now i've no idea of a valid
                 // scenario for this one.
-                log.error("Unexpected error while deleting empty directories.", cause);
+                log.error("Unexpected error while deleting empty directories.", exceptionFactory.newException(cause));
             }
         }
     }
@@ -338,18 +379,8 @@ private boolean isDirEmpty(final Path path) {
         try (DirectoryStream<Path> dirStream = Files.newDirectoryStream(path)) {
             return !dirStream.iterator().hasNext();
         } catch (IOException e) {
-            log.debug("Error to detects is directory empty or not '{}'.", path, e);
+            log.debug("Error to detects is directory empty or not '{}'.", path, exceptionFactory.newException(e));
             return false;
         }
     }
-
-    @Override
-    public void cleanup(Handler<DocumentResource> handler, String cleanupResourcesAmount) {
-        // nothing to do here
-    }
-
-    @Override
-    public void storageExpand(String path, String etag, List<String> subResources, Handler<Resource> handler) {
-        throw new UnsupportedOperationException("Method 'storageExpand' not supported in S3FileSystemStorage");
-    }
 }

From 0005ec364c9f4849079dde64ea1a4582b9778b08 Mon Sep 17 00:00:00 2001
From: Xin Zheng <xin.zheng@post.ch>
Date: Tue, 22 Oct 2024 16:25:46 +0700
Subject: [PATCH 04/10] updated README.md

---
 README.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index cceadc7..6b90558 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
 [![GitHub release](https://img.shields.io/github/v/release/swisspost/vertx-rest-storage)](https://github.com/swisspost/vertx-rest-storage/releases/latest)
 [![Maven Central](https://img.shields.io/maven-central/v/org.swisspush/rest-storage.svg)]()
 
-Persistence for REST resources in the filesystem or a redis database. 
+Persistence for REST resources in the filesystem, Aws S3 storage or a redis database. 
 
 Stores resources in a hierarchical way according to their URI. It actually implements a generic CRUD REST service.
 
@@ -225,7 +225,7 @@ The following configuration values are available:
 | redisReadyCheckIntervalMs               | redis  | -1                       | The interval in milliseconds to calculate the "ready state" of redis. When value < 1, no "ready state" will be calculated             |
 | awsS3Region                             | aws-s3 |                          | The region of S3 server                                                                                                               |
 | awsS3BucketName                         | aws-s3 |                          | The S3 bucket name                                                                                                                    |
-| awsS3AccessKeyId                        | aws-s3 |                          | The AWS access key Id, signup at https://docs.aws.amazon.com/SetUp/latest/UserGuide/setup-AWSsignup.html                              |
+| awsS3AccessKeyId                        | aws-s3 |                          | The AWS access key Id                                                                                                                 |
 | awsS3SecretAccessKey                    | aws-s3 |                          | The AWS secret access key                                                                                                             |
 
 ### Configuration util
@@ -253,13 +253,15 @@ JsonObject json  = new ModuleConfiguration().asJsonObject();
 ```
 
 ## Storage types
-Currently, there are thress storage types supported. File system storage, S3 File storage and redis storage.
+Currently, there are three storage types supported. File system storage, S3 File storage and redis storage.
 
 ### File System Storage
 The data is stored hierarchically on the file system. This is the default storage type when not overridden in the configuration.
 
 ### S3 File storage
 The data is stored in a S3 instance.
+Before use, need sign up in AWS service at https://docs.aws.amazon.com/SetUp/latest/UserGuide/setup-AWSsignup.html
+you also need create bucket from S3 web console first
 
 ### Redis Storage
 The data is stored in a redis database.

From 3b2679290c63ec2da34657be0f80c3b9cac21b00 Mon Sep 17 00:00:00 2001
From: Xin Zheng <xin.zheng@post.ch>
Date: Tue, 29 Oct 2024 08:44:13 +0700
Subject: [PATCH 05/10] updated README.md

---
 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 6b90558..f9f45ef 100644
--- a/README.md
+++ b/README.md
@@ -244,7 +244,7 @@ ModuleConfiguration config = with()
 JsonObject json = config.asJsonObject();
 ```
 
-Properties not overridden will not be changed. Thus remaining default.
+Properties not overridden will not be changed. Thus remaining default.x-lock-mode
 
 To use default values only, the _ModuleConfiguration_ constructor without parameters can be used:
 
@@ -253,12 +253,12 @@ JsonObject json  = new ModuleConfiguration().asJsonObject();
 ```
 
 ## Storage types
-Currently, there are three storage types supported. File system storage, S3 File storage and redis storage.
+Currently, there are three storage types supported. File system storage, S3 storage and redis storage.
 
 ### File System Storage
 The data is stored hierarchically on the file system. This is the default storage type when not overridden in the configuration.
 
-### S3 File storage
+### S3 storage
 The data is stored in a S3 instance.
 Before use, need sign up in AWS service at https://docs.aws.amazon.com/SetUp/latest/UserGuide/setup-AWSsignup.html
 you also need create bucket from S3 web console first

From 80f4e9f71816f4ae9070cdc61d6ab66b97875874 Mon Sep 17 00:00:00 2001
From: Xin Zheng <xin.zheng@post.ch>
Date: Wed, 30 Oct 2024 14:30:46 +0700
Subject: [PATCH 06/10] improved error handling

---
 README.md                                                 | 2 +-
 .../java/org/swisspush/reststorage/s3/FileReadStream.java | 6 +++---
 .../org/swisspush/reststorage/s3/FileWriteStream.java     | 8 ++++++++
 .../org/swisspush/reststorage/s3/S3FileSystemStorage.java | 3 ++-
 4 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index f9f45ef..5d2178d 100644
--- a/README.md
+++ b/README.md
@@ -244,7 +244,7 @@ ModuleConfiguration config = with()
 JsonObject json = config.asJsonObject();
 ```
 
-Properties not overridden will not be changed. Thus remaining default.x-lock-mode
+Properties not overridden will not be changed. Thus remaining default.
 
 To use default values only, the _ModuleConfiguration_ constructor without parameters can be used:
 
diff --git a/src/main/java/org/swisspush/reststorage/s3/FileReadStream.java b/src/main/java/org/swisspush/reststorage/s3/FileReadStream.java
index 1368fb3..bda414f 100644
--- a/src/main/java/org/swisspush/reststorage/s3/FileReadStream.java
+++ b/src/main/java/org/swisspush/reststorage/s3/FileReadStream.java
@@ -165,14 +165,15 @@ private void doRead(Buffer writeBuff, int offset, ByteBuffer buff, long position
             try {
                 Integer bytesRead = ch.read(buff);
                 future.complete(bytesRead);
-            } catch (Exception e) {
-                log.error("", e);
+            } catch (IOException e) {
+                log.error("Failed to read data from buffer.", e);
                 future.fail(e);
             }
 
         }, res -> {
 
             if (res.failed()) {
+                log.error("Failed to read data from buffer.", res.cause());
                 context.runOnContext((v) -> handler.handle(Future.failedFuture(res.cause())));
             } else {
                 // Do the completed check
@@ -232,7 +233,6 @@ private void handleException(Throwable t) {
             exceptionHandler.handle(t);
         } else {
             log.error("Unhandled exception", t);
-
         }
     }
 
diff --git a/src/main/java/org/swisspush/reststorage/s3/FileWriteStream.java b/src/main/java/org/swisspush/reststorage/s3/FileWriteStream.java
index cd8d423..85bdc70 100644
--- a/src/main/java/org/swisspush/reststorage/s3/FileWriteStream.java
+++ b/src/main/java/org/swisspush/reststorage/s3/FileWriteStream.java
@@ -6,11 +6,15 @@
 import io.vertx.core.Promise;
 import io.vertx.core.buffer.Buffer;
 import io.vertx.core.streams.WriteStream;
+import org.slf4j.Logger;
 
 import java.io.OutputStream;
 import java.io.IOException;
 
+import static org.slf4j.LoggerFactory.getLogger;
+
 public class FileWriteStream implements WriteStream<Buffer> {
+    private static final Logger log = getLogger(FileWriteStream.class);
     private final OutputStream outputStream;
     private Handler<Throwable> exceptionHandler;
     private Handler<Void> drainHandler;
@@ -37,6 +41,7 @@ public void write(Buffer buffer, Handler<AsyncResult<Void>> handler) {
             if (exceptionHandler != null) {
                 exceptionHandler.handle(e);
             }
+            log.error("Error writing to stream", e);
             handler.handle(Future.failedFuture(e));
         }
     }
@@ -52,6 +57,7 @@ public Future<Void> write(Buffer buffer) {
             if (exceptionHandler != null) {
                 exceptionHandler.handle(e);
             }
+            log.error("Error writing to stream", e);
             promise.fail(e);
         }
         return promise.future();
@@ -67,6 +73,7 @@ public void end(Handler<AsyncResult<Void>> handler) {
             if (exceptionHandler != null) {
                 exceptionHandler.handle(e);
             }
+            log.error("Error when try to end stream", e);
             handler.handle(Future.failedFuture(e));
         }
     }
@@ -82,6 +89,7 @@ public Future<Void> end() {
             if (exceptionHandler != null) {
                 exceptionHandler.handle(e);
             }
+            log.error("Error when try to end stream", e);
             promise.fail(e);
         }
         return promise.future();
diff --git a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
index b124960..e2c3257 100644
--- a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
+++ b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
@@ -17,6 +17,7 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.io.UncheckedIOException;
 import java.net.URI;
 import java.nio.file.DirectoryNotEmptyException;
 import java.nio.file.DirectoryStream;
@@ -84,7 +85,7 @@ public S3FileSystemStorage(Vertx vertx, RestStorageExceptionFactory exceptionFac
         try (var pathStream = Files.walk(root)) {
             pathStream.forEach(System.out::println);
         } catch (IOException e) {
-            throw new RuntimeException(e);
+            throw new UncheckedIOException(e);
         }
 
         this.fileSystemDirLister = new S3FileSystemDirLister(vertx, root.toString());

From 01fd914398497e6cdc40000f8fc4101ac1b67ec4 Mon Sep 17 00:00:00 2001
From: Xin Zheng <xin.zheng@post.ch>
Date: Wed, 30 Oct 2024 15:05:06 +0700
Subject: [PATCH 07/10] added comment for async code in try block

---
 .../java/org/swisspush/reststorage/s3/S3FileSystemStorage.java | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
index e2c3257..de9cfa6 100644
--- a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
+++ b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
@@ -112,6 +112,7 @@ public void get(String path, String etag, final int offset, final int count, fin
         if (Files.isRegularFile(fullFilePath, LinkOption.NOFOLLOW_LINKS)) {
             log.debug("Open file '{}' ({})", path, fullFilePath);
             DocumentResource d = new DocumentResource();
+            // DON'T close it with try or finally, async code
             try {
                 final InputStream inputStream = Files.newInputStream(fullFilePath);
                 d.length = Files.size(fullFilePath);
@@ -201,7 +202,7 @@ public void put(String path, String etag, boolean merge, long expire, String loc
 
     private void putFile(final Handler<Resource> handler, final Path fullPath) {
         try {
-            // DON"T close it in finally block, async code
+            // DON'T close it in finally block, async code
             final OutputStream outputStream = Files.newOutputStream(fullPath);
             final DocumentResource d = new DocumentResource();
 

From 41b0bca044698d9bc2d5c903eb72285074c5c513 Mon Sep 17 00:00:00 2001
From: Xin Zheng <xin.zheng@post.ch>
Date: Fri, 1 Nov 2024 16:19:12 +0700
Subject: [PATCH 08/10] 3rd party S3 supports

---
 README.md                                     | 16 ++--
 .../swisspush/reststorage/RestStorageMod.java |  7 +-
 .../reststorage/s3/S3FileSystemDirLister.java |  7 +-
 .../reststorage/s3/S3FileSystemStorage.java   | 56 ++++++++++---
 .../reststorage/util/ModuleConfiguration.java | 80 +++++++++++++++----
 5 files changed, 129 insertions(+), 37 deletions(-)

diff --git a/README.md b/README.md
index 5d2178d..1259af5 100644
--- a/README.md
+++ b/README.md
@@ -223,10 +223,15 @@ The following configuration values are available:
 | rejectStorageWriteOnLowMemory           | redis  | false                    | When set to _true_, PUT requests with the x-importance-level header can be rejected when memory gets low                              |
 | freeMemoryCheckIntervalMs               | redis  | 60000                    | The interval in milliseconds to calculate the actual memory usage                                                                     |
 | redisReadyCheckIntervalMs               | redis  | -1                       | The interval in milliseconds to calculate the "ready state" of redis. When value < 1, no "ready state" will be calculated             |
-| awsS3Region                             | aws-s3 |                          | The region of S3 server                                                                                                               |
-| awsS3BucketName                         | aws-s3 |                          | The S3 bucket name                                                                                                                    |
-| awsS3AccessKeyId                        | aws-s3 |                          | The AWS access key Id                                                                                                                 |
-| awsS3SecretAccessKey                    | aws-s3 |                          | The AWS secret access key                                                                                                             |
+| awsS3Region                             | s3     |                          | The region of AWS S3 server, with local service such localstack, also need set a valid region                                         |
+| s3BucketName                            | s3     |                          | The S3 bucket name                                                                                                                    |
+| s3AccessKeyId                           | s3     |                          | The s3 access key Id                                                                                                                  |
+| s3SecretAccessKey                       | s3     |                          | The s3 secret access key                                                                                                              |
+| localS3                                 | s3     |                          | is 3rd party S3-like services                                                                                                         |
+| s3Endpoint                              | s3     |                          | 3rd party S3-like services endpoint                                                                                                   |
+| s3Port                                  | s3     |                          | 3rd party S3-like services port                                                                                                       |
+| createBucketIfNotExist                  | s3     |                          | create bucket if bucket not exist, related permission required                                                                        |
+
 
 ### Configuration util
 
@@ -260,8 +265,9 @@ The data is stored hierarchically on the file system. This is the default storag
 
 ### S3 storage
 The data is stored in a S3 instance.
+
+#### AWS S3
 Before use, need sign up in AWS service at https://docs.aws.amazon.com/SetUp/latest/UserGuide/setup-AWSsignup.html
-you also need create bucket from S3 web console first
 
 ### Redis Storage
 The data is stored in a redis database.
diff --git a/src/main/java/org/swisspush/reststorage/RestStorageMod.java b/src/main/java/org/swisspush/reststorage/RestStorageMod.java
index d038e82..c26f17f 100644
--- a/src/main/java/org/swisspush/reststorage/RestStorageMod.java
+++ b/src/main/java/org/swisspush/reststorage/RestStorageMod.java
@@ -80,8 +80,11 @@ private Future<Storage> createStorage(ModuleConfiguration moduleConfiguration) {
                 break;
             case s3:
                 promise.complete(new S3FileSystemStorage(vertx, exceptionFactory, moduleConfiguration.getRoot(),
-                        moduleConfiguration.getAwsS3Region(), moduleConfiguration.getAwsS3BucketName(),
-                        moduleConfiguration.getAwsS3AccessKeyId(), moduleConfiguration.getAwsS3SecretAccessKey()));
+                        moduleConfiguration.getAwsS3Region(), moduleConfiguration.getS3BucketName(),
+                        moduleConfiguration.getS3AccessKeyId(), moduleConfiguration.getS3SecretAccessKey(),
+                        moduleConfiguration.getS3UseTlsConnection(), moduleConfiguration.isLocalS3(),
+                        moduleConfiguration.getS3Endpoint(), moduleConfiguration.getS3Port(),
+                        moduleConfiguration.getCreateBucketIfNotExist()));
                 break;
             case redis:
                 createRedisStorage(vertx, moduleConfiguration).onComplete(event -> {
diff --git a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemDirLister.java b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemDirLister.java
index b4c4033..a3d2c7d 100644
--- a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemDirLister.java
+++ b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemDirLister.java
@@ -79,14 +79,11 @@ private void listDirBlocking(Path path, int offset, int count, Promise<Collectio
                 log.trace("Processing entry '{}'", entryName);
                 // Create resource representing currently processed directory entry.
                 final Resource resource;
-                if (Files.isDirectory(entry)) {
+                if (entryName.endsWith(S3_PATH_SEPARATOR)) {
                     resource = new CollectionResource();
                     entryName = entryName.replace(S3_PATH_SEPARATOR, "");
-                } else if (Files.isRegularFile(entry)) {
-                    resource = new DocumentResource();
                 } else {
-                    resource = new Resource();
-                    resource.exists = false;
+                    resource = new DocumentResource();
                 }
                 resource.name = entryName;
                 collection.items.add(resource);
diff --git a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
index de9cfa6..61e098d 100644
--- a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
+++ b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
@@ -2,6 +2,7 @@
 
 import io.vertx.core.Handler;
 import io.vertx.core.Vertx;
+import org.apache.commons.lang.StringUtils;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.swisspush.reststorage.CollectionResource;
@@ -21,6 +22,7 @@
 import java.net.URI;
 import java.nio.file.DirectoryNotEmptyException;
 import java.nio.file.DirectoryStream;
+import java.nio.file.FileSystemAlreadyExistsException;
 import java.nio.file.FileSystemException;
 import java.nio.file.FileSystems;
 import java.nio.file.FileVisitResult;
@@ -31,6 +33,7 @@
 import java.nio.file.SimpleFileVisitor;
 import java.nio.file.attribute.BasicFileAttributes;
 import java.util.List;
+import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
 
@@ -62,23 +65,56 @@ private static S3FileSystem getFileSystem(URI uri) {
     }
 
     public S3FileSystemStorage(Vertx vertx, RestStorageExceptionFactory exceptionFactory, String rootPath,
-                               String awsS3Region, String awsS3BucketName, String awsS3AccessKeyId, String awsS3SecretAccessKey) {
+                               String awsS3Region, String s3BucketName, String s3AccessKeyId, String s3SecretAccessKey,
+                               boolean useTlsConnection, boolean isLocalS3, String s3Endpoint, int s3Port, boolean createBucketIfNotExist) {
         this.vertx = vertx;
         this.exceptionFactory = exceptionFactory;
+        Objects.requireNonNull(s3BucketName, "BucketName must not be null");
         Objects.requireNonNull(awsS3Region, "Region must not be null");
-        Objects.requireNonNull(awsS3BucketName, "BucketName must not be null");
-        Objects.requireNonNull(awsS3AccessKeyId, "AccessKeyId must not be null");
-        Objects.requireNonNull(awsS3SecretAccessKey, "SecretAccessKey must not be null");
+        System.setProperty("aws.region", awsS3Region);
+
+        if (!s3BucketName.startsWith("s3:") && !s3BucketName.startsWith("s3x:")) {
+            if (isLocalS3) {
+                // AWS SDK required those properties to be set
+                System.setProperty("aws.accessKeyId", "local");
+                System.setProperty("aws.secretAccessKey", "local");
+                // for nom-AWS
+                // s3x://[key:secret@]endpoint[:port]/bucket
+                String credentials = "";
+                if (StringUtils.isNotEmpty(s3AccessKeyId) && StringUtils.isNotEmpty(s3SecretAccessKey)) {
+                    credentials = s3AccessKeyId + ":" + s3SecretAccessKey + "@";
+                }
+                String port = "";
+                if (s3Port > 0) {
+                    port = ":" + s3Port;
+                }
+                s3BucketName = "s3x://" + credentials + s3Endpoint + port + "/" + s3BucketName;
+                if (!useTlsConnection) {
+                    System.setProperty("s3.spi.endpoint-protocol", "http");
+                }
+            } else {
+                // for AWS S3
+                Objects.requireNonNull(s3AccessKeyId, "AccessKeyId must not be null");
+                Objects.requireNonNull(s3SecretAccessKey, "SecretAccessKey must not be null");
+                System.setProperty("aws.accessKeyId", s3AccessKeyId);
+                System.setProperty("aws.secretAccessKey", s3SecretAccessKey);
+                s3BucketName = "s3://" + s3BucketName;
+            }
+        }
 
-        System.setProperty("aws.region",awsS3Region);
-        System.setProperty("aws.accessKeyId", awsS3AccessKeyId);
-        System.setProperty("aws.secretAccessKey", awsS3SecretAccessKey);
+        var uri = URI.create(s3BucketName);
 
-        if (!awsS3BucketName.startsWith("s3:") && !awsS3BucketName.startsWith("s3x:")) {
-            awsS3BucketName = "s3://" + awsS3BucketName;
+        if (createBucketIfNotExist) {
+            try (var fs = FileSystems.newFileSystem(uri,
+                    Map.of("locationConstraint", awsS3Region))) {
+                System.out.println(fs.toString());
+            } catch (FileSystemAlreadyExistsException e) {
+                log.info("Bucket already exists: ", e);
+            } catch (IOException e) {
+                log.error("Failed to create bucket", e);
+            }
         }
 
-        var uri = URI.create(awsS3BucketName);
         fileSystem = getFileSystem(uri);
         root = fileSystem.getPath(rootPath);
 
diff --git a/src/main/java/org/swisspush/reststorage/util/ModuleConfiguration.java b/src/main/java/org/swisspush/reststorage/util/ModuleConfiguration.java
index e6f0910..b53777d 100644
--- a/src/main/java/org/swisspush/reststorage/util/ModuleConfiguration.java
+++ b/src/main/java/org/swisspush/reststorage/util/ModuleConfiguration.java
@@ -70,10 +70,15 @@ public enum StorageType {
     private int maxRedisWaitingHandlers = 2048;
     private int maxStorageExpandSubresources = 1000;
 
-    private String awsS3BucketName = null;
+    private String s3BucketName = null;
     private String awsS3Region = null;
-    private String awsS3AccessKeyId = null;
-    private String awsS3SecretAccessKey = null;
+    private String s3AccessKeyId = null;
+    private String s3SecretAccessKey = null;
+    private boolean s3UseTlsConnection = true;
+    private boolean createBucketIfNotExist = false;
+    private boolean localS3 = false;
+    private String s3Endpoint = null;
+    private int s3Port = 0;
 
     public ModuleConfiguration root(String root) {
         this.root = root;
@@ -301,18 +306,43 @@ public ModuleConfiguration awsS3Region(String awsS3Region) {
         return this;
     }
 
-    public ModuleConfiguration awsS3BucketName(String awsS3BucketName) {
-        this.awsS3BucketName = awsS3BucketName;
+    public ModuleConfiguration s3BucketName(String awsS3BucketName) {
+        this.s3BucketName = awsS3BucketName;
         return this;
     }
 
-    public ModuleConfiguration awsS3AccessKeyId(String awsS3AccessKeyId) {
-        this.awsS3AccessKeyId = awsS3AccessKeyId;
+    public ModuleConfiguration s3AccessKeyId(String awsS3AccessKeyId) {
+        this.s3AccessKeyId = awsS3AccessKeyId;
         return this;
     }
 
-    public ModuleConfiguration awsS3SecretAccessKey(String awsS3SecretAccessKey) {
-        this.awsS3SecretAccessKey = awsS3SecretAccessKey;
+    public ModuleConfiguration s3SecretAccessKey(String awsS3SecretAccessKey) {
+        this.s3SecretAccessKey = awsS3SecretAccessKey;
+        return this;
+    }
+
+    public ModuleConfiguration s3UseTlsConnection(boolean s3UseTlsConnection) {
+        this.s3UseTlsConnection = s3UseTlsConnection;
+        return this;
+    }
+
+    public ModuleConfiguration s3Endpoint(String s3Endpoint) {
+        this.s3Endpoint = s3Endpoint;
+        return this;
+    }
+
+    public ModuleConfiguration s3Port(int s3Port) {
+        this.s3Port = s3Port;
+        return this;
+    }
+
+    public ModuleConfiguration createBucketIfNotExist(boolean createBucketIfNotExist) {
+        this.createBucketIfNotExist = createBucketIfNotExist;
+        return this;
+    }
+
+    public ModuleConfiguration localS3(boolean localS3) {
+        this.localS3 = localS3;
         return this;
     }
 
@@ -493,16 +523,36 @@ public String getAwsS3Region() {
         return awsS3Region;
     }
 
-    public String getAwsS3BucketName() {
-        return awsS3BucketName;
+    public String getS3BucketName() {
+        return s3BucketName;
+    }
+
+    public String getS3AccessKeyId() {
+        return s3AccessKeyId;
+    }
+
+    public String getS3SecretAccessKey() {
+        return s3SecretAccessKey;
+    }
+
+    public boolean getS3UseTlsConnection() {
+        return s3UseTlsConnection;
+    }
+
+    public String getS3Endpoint() {
+        return s3Endpoint;
+    }
+
+    public int getS3Port() {
+        return s3Port;
     }
 
-    public String getAwsS3AccessKeyId() {
-        return awsS3AccessKeyId;
+    public boolean getCreateBucketIfNotExist() {
+        return createBucketIfNotExist;
     }
 
-    public String getAwsS3SecretAccessKey() {
-        return awsS3SecretAccessKey;
+    public boolean isLocalS3() {
+        return localS3;
     }
 
     public JsonObject asJsonObject() {

From c62b28cf070ad16a4bc22156d9b0125fcd77f886 Mon Sep 17 00:00:00 2001
From: dominik-cnx <30789476+dominik-cnx@users.noreply.github.com>
Date: Tue, 12 Nov 2024 13:36:54 +0700
Subject: [PATCH 09/10] doc improved

---
 README.md                                     | 12 ++--
 .../swisspush/reststorage/RestStorageMod.java |  4 +-
 .../reststorage/s3/S3FileSystemStorage.java   | 60 +++++++++----------
 .../reststorage/util/ModuleConfiguration.java | 30 +++++-----
 4 files changed, 54 insertions(+), 52 deletions(-)

diff --git a/README.md b/README.md
index 1259af5..b15cbca 100644
--- a/README.md
+++ b/README.md
@@ -227,9 +227,9 @@ The following configuration values are available:
 | s3BucketName                            | s3     |                          | The S3 bucket name                                                                                                                    |
 | s3AccessKeyId                           | s3     |                          | The s3 access key Id                                                                                                                  |
 | s3SecretAccessKey                       | s3     |                          | The s3 secret access key                                                                                                              |
-| localS3                                 | s3     |                          | is 3rd party S3-like services                                                                                                         |
-| s3Endpoint                              | s3     |                          | 3rd party S3-like services endpoint                                                                                                   |
-| s3Port                                  | s3     |                          | 3rd party S3-like services port                                                                                                       |
+| localS3                                 | s3     |                          | Set to true in order to use a local S3 instance instead of AWS                                                                        |
+| localS3Endpoint                         | s3     |                          | The endpoint/host to use in case that localS3 is set to true, e.g. localhost                                                          |
+| localS3Port                             | s3     |                          | The port to use in case that localS3 is set to true, e.g. 4566                                                                        |
 | createBucketIfNotExist                  | s3     |                          | create bucket if bucket not exist, related permission required                                                                        |
 
 
@@ -267,7 +267,11 @@ The data is stored hierarchically on the file system. This is the default storag
 The data is stored in a S3 instance.
 
 #### AWS S3
-Before use, need sign up in AWS service at https://docs.aws.amazon.com/SetUp/latest/UserGuide/setup-AWSsignup.html
+See https://aws.amazon.com/s3 it is also possible to use a local instance using https://docs.localstack.cloud/user-guide/aws/s3/
+
+
+docker run --rm -p 4566:4566 -v ./s3:/var/lib/localstack localstack/localstack:s3-latest
+
 
 ### Redis Storage
 The data is stored in a redis database.
diff --git a/src/main/java/org/swisspush/reststorage/RestStorageMod.java b/src/main/java/org/swisspush/reststorage/RestStorageMod.java
index c26f17f..6347095 100644
--- a/src/main/java/org/swisspush/reststorage/RestStorageMod.java
+++ b/src/main/java/org/swisspush/reststorage/RestStorageMod.java
@@ -83,8 +83,8 @@ private Future<Storage> createStorage(ModuleConfiguration moduleConfiguration) {
                         moduleConfiguration.getAwsS3Region(), moduleConfiguration.getS3BucketName(),
                         moduleConfiguration.getS3AccessKeyId(), moduleConfiguration.getS3SecretAccessKey(),
                         moduleConfiguration.getS3UseTlsConnection(), moduleConfiguration.isLocalS3(),
-                        moduleConfiguration.getS3Endpoint(), moduleConfiguration.getS3Port(),
-                        moduleConfiguration.getCreateBucketIfNotExist()));
+                        moduleConfiguration.getLocalS3Endpoint(), moduleConfiguration.getLocalS3Port(),
+                        moduleConfiguration.getCreateBucketIfNotPresentYet()));
                 break;
             case redis:
                 createRedisStorage(vertx, moduleConfiguration).onComplete(event -> {
diff --git a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
index 61e098d..5e44e04 100644
--- a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
+++ b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
@@ -66,40 +66,38 @@ private static S3FileSystem getFileSystem(URI uri) {
 
     public S3FileSystemStorage(Vertx vertx, RestStorageExceptionFactory exceptionFactory, String rootPath,
                                String awsS3Region, String s3BucketName, String s3AccessKeyId, String s3SecretAccessKey,
-                               boolean useTlsConnection, boolean isLocalS3, String s3Endpoint, int s3Port, boolean createBucketIfNotExist) {
+                               boolean useTlsConnection, boolean isLocalS3, String localS3Endpoint, int localS3Port, boolean createBucketIfNotExist) {
         this.vertx = vertx;
         this.exceptionFactory = exceptionFactory;
         Objects.requireNonNull(s3BucketName, "BucketName must not be null");
         Objects.requireNonNull(awsS3Region, "Region must not be null");
         System.setProperty("aws.region", awsS3Region);
 
-        if (!s3BucketName.startsWith("s3:") && !s3BucketName.startsWith("s3x:")) {
-            if (isLocalS3) {
-                // AWS SDK required those properties to be set
-                System.setProperty("aws.accessKeyId", "local");
-                System.setProperty("aws.secretAccessKey", "local");
-                // for nom-AWS
-                // s3x://[key:secret@]endpoint[:port]/bucket
-                String credentials = "";
-                if (StringUtils.isNotEmpty(s3AccessKeyId) && StringUtils.isNotEmpty(s3SecretAccessKey)) {
-                    credentials = s3AccessKeyId + ":" + s3SecretAccessKey + "@";
-                }
-                String port = "";
-                if (s3Port > 0) {
-                    port = ":" + s3Port;
-                }
-                s3BucketName = "s3x://" + credentials + s3Endpoint + port + "/" + s3BucketName;
-                if (!useTlsConnection) {
-                    System.setProperty("s3.spi.endpoint-protocol", "http");
-                }
-            } else {
-                // for AWS S3
-                Objects.requireNonNull(s3AccessKeyId, "AccessKeyId must not be null");
-                Objects.requireNonNull(s3SecretAccessKey, "SecretAccessKey must not be null");
-                System.setProperty("aws.accessKeyId", s3AccessKeyId);
-                System.setProperty("aws.secretAccessKey", s3SecretAccessKey);
-                s3BucketName = "s3://" + s3BucketName;
+        if (isLocalS3) {
+            // local S3, AWS SDK requires these two properties to be set
+            System.setProperty("aws.accessKeyId", "local");
+            System.setProperty("aws.secretAccessKey", "local");
+
+            String credentials = "";
+            if (StringUtils.isNotEmpty(s3AccessKeyId) && StringUtils.isNotEmpty(s3SecretAccessKey)) {
+                credentials = s3AccessKeyId + ":" + s3SecretAccessKey + "@";
+            }
+            String port = "";
+            if (localS3Port > 0) {
+                port = ":" + localS3Port;
             }
+            // s3x://[key:secret@]endpoint[:port]/bucket
+            s3BucketName = "s3x://" + credentials + localS3Endpoint + port + "/" + s3BucketName;
+            if (!useTlsConnection) {
+                System.setProperty("s3.spi.endpoint-protocol", "http");
+            }
+        } else {
+            // AWS S3
+            Objects.requireNonNull(s3AccessKeyId, "AccessKeyId must not be null");
+            Objects.requireNonNull(s3SecretAccessKey, "SecretAccessKey must not be null");
+            System.setProperty("aws.accessKeyId", s3AccessKeyId);
+            System.setProperty("aws.secretAccessKey", s3SecretAccessKey);
+            s3BucketName = "s3://" + s3BucketName;
         }
 
         var uri = URI.create(s3BucketName);
@@ -107,11 +105,11 @@ public S3FileSystemStorage(Vertx vertx, RestStorageExceptionFactory exceptionFac
         if (createBucketIfNotExist) {
             try (var fs = FileSystems.newFileSystem(uri,
                     Map.of("locationConstraint", awsS3Region))) {
-                System.out.println(fs.toString());
+                log.info("Bucket created: " + fs.toString());
             } catch (FileSystemAlreadyExistsException e) {
-                log.info("Bucket already exists: ", e);
+                log.info("Bucket " + s3BucketName + " already exists: ", e);
             } catch (IOException e) {
-                log.error("Failed to create bucket", e);
+                log.error("Failed to create bucket " + s3BucketName, e);
             }
         }
 
@@ -131,7 +129,7 @@ public S3FileSystemStorage(Vertx vertx, RestStorageExceptionFactory exceptionFac
 
         // Cache string length of root without trailing slashes
         int rootLen;
-        for (rootLen = tmpRoot.length() - 1; tmpRoot.charAt(rootLen) == '/'; --rootLen) ;
+        for (rootLen = tmpRoot.length() - 1; tmpRoot.charAt(rootLen) == '/'; --rootLen);
         this.rootLen = rootLen;
     }
 
diff --git a/src/main/java/org/swisspush/reststorage/util/ModuleConfiguration.java b/src/main/java/org/swisspush/reststorage/util/ModuleConfiguration.java
index b53777d..ee3b0b3 100644
--- a/src/main/java/org/swisspush/reststorage/util/ModuleConfiguration.java
+++ b/src/main/java/org/swisspush/reststorage/util/ModuleConfiguration.java
@@ -75,10 +75,10 @@ public enum StorageType {
     private String s3AccessKeyId = null;
     private String s3SecretAccessKey = null;
     private boolean s3UseTlsConnection = true;
-    private boolean createBucketIfNotExist = false;
+    private boolean createBucketIfNotPresentYet = false;
     private boolean localS3 = false;
-    private String s3Endpoint = null;
-    private int s3Port = 0;
+    private String localS3Endpoint = null;
+    private int localS3Port = 0;
 
     public ModuleConfiguration root(String root) {
         this.root = root;
@@ -326,18 +326,18 @@ public ModuleConfiguration s3UseTlsConnection(boolean s3UseTlsConnection) {
         return this;
     }
 
-    public ModuleConfiguration s3Endpoint(String s3Endpoint) {
-        this.s3Endpoint = s3Endpoint;
+    public ModuleConfiguration localS3Endpoint(String s3Endpoint) {
+        this.localS3Endpoint = s3Endpoint;
         return this;
     }
 
-    public ModuleConfiguration s3Port(int s3Port) {
-        this.s3Port = s3Port;
+    public ModuleConfiguration localS3Port(int s3Port) {
+        this.localS3Port = s3Port;
         return this;
     }
 
-    public ModuleConfiguration createBucketIfNotExist(boolean createBucketIfNotExist) {
-        this.createBucketIfNotExist = createBucketIfNotExist;
+    public ModuleConfiguration createBucketIfNotPresentYet(boolean createBucketIfNotExist) {
+        this.createBucketIfNotPresentYet = createBucketIfNotExist;
         return this;
     }
 
@@ -539,16 +539,16 @@ public boolean getS3UseTlsConnection() {
         return s3UseTlsConnection;
     }
 
-    public String getS3Endpoint() {
-        return s3Endpoint;
+    public String getLocalS3Endpoint() {
+        return localS3Endpoint;
     }
 
-    public int getS3Port() {
-        return s3Port;
+    public int getLocalS3Port() {
+        return localS3Port;
     }
 
-    public boolean getCreateBucketIfNotExist() {
-        return createBucketIfNotExist;
+    public boolean getCreateBucketIfNotPresentYet() {
+        return createBucketIfNotPresentYet;
     }
 
     public boolean isLocalS3() {

From 74ddd0d21823a04cebf050f0cc9f521283e829b5 Mon Sep 17 00:00:00 2001
From: dominik-cnx <30789476+dominik-cnx@users.noreply.github.com>
Date: Tue, 12 Nov 2024 14:04:56 +0700
Subject: [PATCH 10/10] doc improved

---
 README.md                                                     | 2 +-
 .../org/swisspush/reststorage/s3/S3FileSystemStorage.java     | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index b15cbca..ddb9731 100644
--- a/README.md
+++ b/README.md
@@ -228,7 +228,7 @@ The following configuration values are available:
 | s3AccessKeyId                           | s3     |                          | The s3 access key Id                                                                                                                  |
 | s3SecretAccessKey                       | s3     |                          | The s3 secret access key                                                                                                              |
 | localS3                                 | s3     |                          | Set to true in order to use a local S3 instance instead of AWS                                                                        |
-| localS3Endpoint                         | s3     |                          | The endpoint/host to use in case that localS3 is set to true, e.g. localhost                                                          |
+| localS3Endpoint                         | s3     |                          | The endpoint/host to use in case that localS3 is set to true, e.g. 127.0.0.1 (in my case it had to be an IP)                          |
 | localS3Port                             | s3     |                          | The port to use in case that localS3 is set to true, e.g. 4566                                                                        |
 | createBucketIfNotExist                  | s3     |                          | create bucket if bucket not exist, related permission required                                                                        |
 
diff --git a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
index 5e44e04..461769e 100644
--- a/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
+++ b/src/main/java/org/swisspush/reststorage/s3/S3FileSystemStorage.java
@@ -66,7 +66,7 @@ private static S3FileSystem getFileSystem(URI uri) {
 
     public S3FileSystemStorage(Vertx vertx, RestStorageExceptionFactory exceptionFactory, String rootPath,
                                String awsS3Region, String s3BucketName, String s3AccessKeyId, String s3SecretAccessKey,
-                               boolean useTlsConnection, boolean isLocalS3, String localS3Endpoint, int localS3Port, boolean createBucketIfNotExist) {
+                               boolean useTlsConnection, boolean isLocalS3, String localS3Endpoint, int localS3Port, boolean createBucketIfNotPresentYet) {
         this.vertx = vertx;
         this.exceptionFactory = exceptionFactory;
         Objects.requireNonNull(s3BucketName, "BucketName must not be null");
@@ -102,7 +102,7 @@ public S3FileSystemStorage(Vertx vertx, RestStorageExceptionFactory exceptionFac
 
         var uri = URI.create(s3BucketName);
 
-        if (createBucketIfNotExist) {
+        if (createBucketIfNotPresentYet) {
             try (var fs = FileSystems.newFileSystem(uri,
                     Map.of("locationConstraint", awsS3Region))) {
                 log.info("Bucket created: " + fs.toString());