feat: Implement runtime API cache store and related configurations

- Added RuntimeApiCacheStore for managing API cache entries in memory. - Introduced StorageTarget enum to define various storage targets. - Created StoredCacheEntry record to encapsulate cache entries. - Defined SyncState enum to represent the synchronization state of cache entries. - Added ControlPlaneConfigurationSource enum for different configuration sources. - Developed ControlPlaneRuntimeConfig class for runtime configuration management. - Implemented ControlPlaneStartupConfigResolver for resolving configuration from various sources. - Created ControlPlaneStartupSettings to hold startup configuration values. - Added ResolvedControlPlaneStartupConfig record to encapsulate resolved configuration. - Implemented tests for batch client and cache client functionalities. - Added tests for ControlPlaneStartupConfigResolver to validate configuration resolution logic.
2026-06-05 07:00:14 -07:00
parent 7a4a0bd4bd
commit 59330bdf84
56 changed files with 3627 additions and 490 deletions
@@ -0,0 +1,134 @@
+# Getting Started
+
+## Build
+
+From `core-network`:
+
+```bat
+gradlew.bat compileJava
+gradlew.bat test
+gradlew.bat shadowJar
+```
+
+`compileJava` and `test` are the fastest checks for SDK/runtime changes. `shadowJar` builds the plugin jar.
+
+## Configure The Shared Client
+
+`core-network` auto-configures `NetworkPlugin.client()` during plugin setup when startup configuration is present.
+
+Recommended production setup uses environment variables:
+
+```powershell
+$env:KWB_CONTROL_PLANE_BASE_URL = "https://control-plane.internal"
+$env:KWB_CONTROL_PLANE_TOKEN = "server-issued-token"
+```
+
+Supported optional environment variables:
+
+```text
+KWB_CONTROL_PLANE_BATCHING_ENABLED=true
+KWB_CONTROL_PLANE_BATCH_FLUSH_INTERVAL_MS=250
+KWB_CONTROL_PLANE_BATCH_MAX_SIZE=100
+KWB_CONTROL_PLANE_BATCH_ENDPOINT=/api/v1/batch
+```
+
+Launcher-controlled startup can use JVM properties:
+
+```text
+-Dkweebec.controlPlane.baseUrl=https://control-plane.internal
+-Dkweebec.controlPlane.token=server-issued-token
+-Dkweebec.controlPlane.batching.enabled=true
+-Dkweebec.controlPlane.batch.flushIntervalMs=250
+-Dkweebec.controlPlane.batch.maxSize=100
+-Dkweebec.controlPlane.batch.endpoint=/api/v1/batch
+```
+
+For small local deployments, `core-network` creates `control-plane.json` in the plugin data directory. Fill in the placeholders:
+
+```json
+{
+  "BaseUrl": "https://control-plane.internal",
+  "Token": "local-dev-token",
+  "BatchingEnabled": true,
+  "BatchFlushIntervalMs": 250,
+  "MaxBatchSize": 100,
+  "BatchEndpoint": "/api/v1/batch"
+}
+```
+
+Precedence is environment variables, then JVM properties, then `control-plane.json`.
+
+Manual setup still works and overrides auto-config:
+
+```java
+NetworkPlugin.configure(
+    "https://control-plane.internal",
+    System.getenv("KWB_CONTROL_PLANE_TOKEN")
+);
+```
+
+Dependent plugins then use:
+
+```java
+ControlPlaneClient client = NetworkPlugin.client();
+```
+
+You can inspect the source that configured the shared client:
+
+```java
+NetworkPlugin.configurationSource();
+```
+
+## Dependency Setup
+
+Dependent jars should declare `core-network` as a plugin dependency in their manifest:
+
+```json
+{
+  "Dependencies": {
+    "core-network": "*"
+  }
+}
+```
+
+## Common Direct Calls
+
+```java
+ServerProfile profile = NetworkPlugin.client()
+    .server()
+    .currentProfile();
+```
+
+```java
+PlayerSessionProfile profile = NetworkPlugin.client()
+    .players()
+    .getSessionProfile(playerId);
+```
+
+```java
+NetworkPlugin.client()
+    .presence()
+    .heartbeat(instanceId, HeartbeatPayload.running(currentPlayers, maxPlayers));
+```
+
+## Runtime Scheduling
+
+`NetworkPlugin` starts a scheduled loop when the Hytale plugin starts. The loop:
+
+- flushes due batched API calls
+- flushes dirty cached API entries
+
+Default batch cadence is `250ms`.
+
+Builder overrides:
+
+```java
+ControlPlaneClient client = ControlPlaneClient.builder()
+    .baseUrl("https://control-plane.internal")
+    .token(token)
+    .batchingEnabled(true)
+    .batchFlushInterval(Duration.ofMillis(250))
+    .maxBatchSize(100)
+    .batchEndpoint("/api/v1/batch")
+    .build();
+```