Add http caching client interfaces

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,
+
+    }
+
+}

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();
+
+}