feat: implement query caching system with cache configuration, event listener, and stats monitoring

Author: FllipEis

api/build.gradle.kts

@@ -27,27 +27,27 @@ dependencies {
 
     implementation(rootProject.libs.adventure.api)
     implementation(rootProject.libs.adventure.gson)
+    implementation(rootProject.libs.caffeine)
 }
 
 tasks.named<ShadowJar>("shadowJar") {
     mergeServiceFiles()
 
-    val versionPath = project.version.toString().replace(".", "_").replace("-", "_")
-
-    relocate("io.nats", "app.simplecloud.api.shaded.v${versionPath}.nats")
-    relocate("com.google", "app.simplecloud.api.shaded.v${versionPath}.google")
-    relocate("build.buf", "app.simplecloud.api.shaded.v${versionPath}.buf")
-    relocate("okhttp3", "app.simplecloud.api.shaded.v${versionPath}.okhttp3")
-    relocate("okio", "app.simplecloud.api.shaded.v${versionPath}.okio")
-    relocate("io.gsonfire", "app.simplecloud.api.shaded.v${versionPath}.gsonfire")
-    relocate("org.bouncycastle", "app.simplecloud.api.shaded.v${versionPath}.bouncycastle")
-    relocate("org.intellij", "app.simplecloud.api.shaded.v${versionPath}.intellij")
-    relocate("org.jetbrains", "app.simplecloud.api.shaded.v${versionPath}.jetbrains")
-    relocate("kotlin", "app.simplecloud.api.shaded.v${versionPath}.kotlin")
-
-    relocate("google", "app.simplecloud.api.shaded.v${versionPath}.google")
-    relocate("native", "app.simplecloud.api.shaded.v${versionPath}.native")
-    relocate("core", "app.simplecloud.api.shaded.v${versionPath}.core")
+    relocate("io.nats", "app.simplecloud.api.shaded.nats")
+    relocate("com.google", "app.simplecloud.api.shaded.google")
+    relocate("build.buf", "app.simplecloud.api.shaded.buf")
+    relocate("okhttp3", "app.simplecloud.api.shaded.okhttp3")
+    relocate("okio", "app.simplecloud.api.shaded.okio")
+    relocate("io.gsonfire", "app.simplecloud.api.shaded.gsonfire")
+    relocate("org.bouncycastle", "app.simplecloud.api.shaded.bouncycastle")
+    relocate("org.intellij", "app.simplecloud.api.shaded.intellij")
+    relocate("org.jetbrains", "app.simplecloud.api.shaded.jetbrains")
+    relocate("kotlin", "app.simplecloud.api.shaded.kotlin")
+    relocate("com.github.benmanes.caffeine", "app.simplecloud.api.shaded.caffeine")
+
+    relocate("google", "app.simplecloud.api.shaded.google")
+    relocate("native", "app.simplecloud.api.shaded.native")
+    relocate("core", "app.simplecloud.api.shaded.core")
 
     archiveClassifier.set("")
 }

api/src/main/java/app/simplecloud/api/CloudApi.java

@@ -1,5 +1,7 @@
 package app.simplecloud.api;
 
+import app.simplecloud.api.cache.QueryCache;
+import app.simplecloud.api.cache.QueryKey;
 import app.simplecloud.api.event.EventApi;
 import app.simplecloud.api.group.GroupApi;
 import app.simplecloud.api.internal.CloudApiImpl;
@@ -120,5 +122,25 @@ static CloudApi create(CloudApiOptions options) {
      */
     String getNetworkId();
 
+    /**
+     * Returns the query cache for manual cache operations.
+     *
+     * <p>Use this for manual invalidation or to inspect cache state:
+     * <pre>{@code
+     * // Invalidate a specific server
+     * cloudApi.cache().invalidate(QueryKey.of("server", serverId));
+     *
+     * // Invalidate all servers
+     * cloudApi.cache().invalidateAll(QueryKey.of("servers"));
+     *
+     * // Get cache statistics
+     * CacheStats stats = cloudApi.cache().getStats();
+     * System.out.println("Cache hit rate: " + stats.getHitRate());
+     * }</pre>
+     *
+     * @return the query cache
+     */
+    QueryCache cache();
+
 }
 

api/src/main/java/app/simplecloud/api/CloudApiOptions.java

@@ -1,5 +1,7 @@
 package app.simplecloud.api;
 
+import app.simplecloud.api.cache.CacheConfig;
+
 public class CloudApiOptions {
 
     public final static CloudApiOptions DEFAULT = new Builder().build();
@@ -8,12 +10,14 @@ public class CloudApiOptions {
     private final String controllerUrl;
     private final String networkId;
     private final String networkSecret;
+    private final CacheConfig cacheConfig;
 
     private CloudApiOptions(Builder builder) {
         this.natsUrl = builder.natsUrl;
         this.controllerUrl = builder.controllerUrl;
         this.networkId = builder.networkId;
         this.networkSecret = builder.networkSecret;
+        this.cacheConfig = builder.cacheConfig;
     }
 
     public String getNatsUrl() {
@@ -32,6 +36,15 @@ public String getNetworkSecret() {
         return networkSecret;
     }
 
+    /**
+     * Returns the cache configuration.
+     *
+     * @return the cache configuration
+     */
+    public CacheConfig getCacheConfig() {
+        return cacheConfig;
+    }
+
     public static Builder builder() {
         return new Builder();
     }
@@ -41,6 +54,7 @@ public static class Builder {
         private String controllerUrl;
         private String networkId;
         private String networkSecret;
+        private CacheConfig cacheConfig = CacheConfig.DEFAULT;
 
         public Builder() {
             this.natsUrl = System.getenv().getOrDefault("SIMPLECLOUD_NATS_URL", "nats://platform.simplecloud.app:4222");
@@ -69,6 +83,31 @@ public Builder networkSecret(String networkSecret) {
             return this;
         }
 
+        /**
+         * Sets the cache configuration.
+         *
+         * <p>By default, caching is enabled with sensible defaults.
+         * Use {@link CacheConfig#DISABLED} to disable caching entirely.
+         *
+         * @param cacheConfig the cache configuration
+         * @return this builder
+         */
+        public Builder cache(CacheConfig cacheConfig) {
+            this.cacheConfig = cacheConfig;
+            return this;
+        }
+
+        /**
+         * Disables caching entirely.
+         * Shorthand for {@code cache(CacheConfig.DISABLED)}.
+         *
+         * @return this builder
+         */
+        public Builder disableCache() {
+            this.cacheConfig = CacheConfig.DISABLED;
+            return this;
+        }
+
         public CloudApiOptions build() {
             return new CloudApiOptions(this);
         }