From f137b0c91978c7d990de4e529ee983fda1bfb3e4 Mon Sep 17 00:00:00 2001
From: Smyler <smyler@mail.com>
Date: Sat, 3 Aug 2024 15:07:26 +0200
Subject: [PATCH] Add http caching client interfaces

---
 .../smyler/terramap/http/CacheStatistics.java | 32 +++++++++++++++++
 .../terramap/http/CachingHttpClient.java      | 34 +++++++++++++++++++
 2 files changed, 66 insertions(+)
 create mode 100644 core/src/main/java/net/smyler/terramap/http/CacheStatistics.java
 create mode 100644 core/src/main/java/net/smyler/terramap/http/CachingHttpClient.java

diff --git a/core/src/main/java/net/smyler/terramap/http/CacheStatistics.java b/core/src/main/java/net/smyler/terramap/http/CacheStatistics.java
new file mode 100644
index 00000000..df029d4a
--- /dev/null
+++ b/core/src/main/java/net/smyler/terramap/http/CacheStatistics.java
@@ -0,0 +1,32 @@
+package net.smyler.terramap.http;
+
+/**
+ * Cache usage statistics.
+ *
+ * @param entries   number of entries in the cache
+ * @param size      total storage space used by the cache
+ * @param type      the type of cache in use
+ */
+public record CacheStatistics(long entries, long size, CacheType type) {
+
+    public enum CacheType {
+
+        /**
+         * Cache is fully on disk.
+         */
+        DISK,
+
+        /**
+         * Cache is fully in memory.
+         * Should not be used outside of development.
+         */
+        MEMORY,
+
+        /**
+         * Cache uses a mix of disk and memory storage.
+         */
+        HYBRID,
+
+    }
+
+}
diff --git a/core/src/main/java/net/smyler/terramap/http/CachingHttpClient.java b/core/src/main/java/net/smyler/terramap/http/CachingHttpClient.java
new file mode 100644
index 00000000..e09d0fc9
--- /dev/null
+++ b/core/src/main/java/net/smyler/terramap/http/CachingHttpClient.java
@@ -0,0 +1,34 @@
+package net.smyler.terramap.http;
+
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * ALL http implementation used by Terramap should implement caching,
+ * but may not necessarily expose programmatically for management
+ * (e.g. if Terramap uses Terra++'s http client, Terra++ takes care of
+ * cache management).
+ */
+public interface CachingHttpClient extends HttpClient {
+
+    /**
+     * Computes statistics about the current cache usage.
+     *
+     * @return a future of the client's cache statistics
+     */
+    CompletableFuture<CacheStatistics> cacheStatistics();
+
+    /**
+     * Performs regular maintenance on cache, removing long stale entries etc.
+     *
+     * @return a future containing statistics on the entries that were removed from the cache
+     */
+    CompletableFuture<CacheStatistics> cacheCleanup();
+
+    /**
+     * Fully clears the cache.
+     *
+     * @return a future containing statistics on the entries that were removed from the cache
+     */
+    CompletableFuture<CacheStatistics> cacheClear();
+
+}