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.
This commit is contained in:
2026-06-05 07:00:14 -07:00
parent 7a4a0bd4bd
commit 59330bdf84
56 changed files with 3627 additions and 490 deletions
+102
View File
@@ -0,0 +1,102 @@
# Batched API Calls
Batching lets multiple plugins enqueue control-plane calls that are sent as one HTTP request to `/api/v1/batch`.
Use batching when:
- many plugins read data at the same time
- looped tasks report state periodically
- call latency can be handled asynchronously
Do not use batching when:
- the caller needs a blocking result immediately
- the endpoint should bypass queueing for operational safety
## One-Off Calls
```java
CompletableFuture<ServerProfile> future = NetworkPlugin.client()
.batch()
.get(ProfileEndpoint.VALUE, ProfileEndpoint.VALUE.uri(), ServerProfile.class);
```
```java
CompletableFuture<JsonObject> future = NetworkPlugin.client()
.batch()
.enqueueJson("GET", "/api/v1/server/profile", null);
```
Queued calls complete when the batch loop flushes, or when code calls:
```java
NetworkPlugin.client().batch().flush();
```
## Looped Calls
```java
LoopHandle handle = NetworkPlugin.client().batch().registerLoopedCall(
LoopedApiCall.builder(ServerProfile.class)
.id("server-profile-loop")
.interval(Duration.ofSeconds(5))
.method("GET")
.uri("/api/v1/server/profile")
.onSuccess(profile -> {
// update local state
})
.onFailure(error -> {
// log or mark degraded
})
.build()
);
```
Cancel when no longer needed:
```java
handle.cancel();
```
## Batch Endpoint Contract
Request:
```json
{
"requests": [
{
"id": "generated-call-id",
"method": "GET",
"uri": "/api/v1/server/profile",
"body": null
}
]
}
```
Response:
```json
{
"responses": [
{
"id": "generated-call-id",
"status": 200,
"body": { "data": {} },
"error": null
}
]
}
```
Each item completes independently. A failed item does not fail unrelated futures.
## Defaults
- endpoint: `/api/v1/batch`
- flush interval: `250ms`
- max batch size: `100`
- batching enabled: `true`
Configure with `ControlPlaneClient.builder()`.