Add FileCache Prune REST API endpoint

[x-INFiN1TY-x]

Add FileCache Prune REST API

Introduces a REST API for on-demand pruning of OpenSearch's file cache. This production-ready implementation enables operators to efficiently manage disk space across warm node clusters.

Issue

#19322

Implementation Architecture

Implements OpenSearch's advanced TransportNodesAction pattern for sophisticated multi-node coordination:

REST Layer → Node Transport → Node Resolution → Parallel FileCache Operations

API Specification

Endpoint

POST /_cache/filecache/prune

Parameters

• nodes (optional) — Comma-separated list of node IDs or node selectors (e.g., warm:true)
• node (optional) — Single node ID for targeted operations
• timeout (optional) — Operation timeout (e.g., 30s, 2m, 1h)

Response Format

{
  "acknowledged": true,
  "total_pruned_bytes": 2097152,
  "summary": {
    "total_nodes_targeted": 3,
    "successful_nodes": 2,
    "failed_nodes": 1,
    "total_cache_capacity": 32212254720
  },
  "nodes": {
    "warm-node-1": {
      "name": "opensearch-warm-1",
      "transport_address": "10.0.1.101:9300",
      "host": "warm-1.cluster.local",
      "ip": "10.0.1.101",
      "pruned_bytes": 1048576,
      "cache_capacity": 10737418240
    },
    "warm-node-2": {
      "name": "opensearch-warm-2", 
      "transport_address": "10.0.1.102:9300",
      "host": "warm-2.cluster.local",
      "ip": "10.0.1.102",
      "pruned_bytes": 1048576,
      "cache_capacity": 10737418240
    }
  },
  "failures": [
    {
      "node_id": "warm-node-3",
      "reason": "FileCache prune operation failed",
      "caused_by": "RuntimeException"
    }
  ]
}

Files Added

server/src/main/java/org/opensearch/action/admin/cluster/cache/
├── PruneCacheAction.java
├── PruneCacheRequest.java
├── PruneCacheResponse.java
├── NodePruneCacheResponse.java  [NEW - Advanced node response model]
├── TransportPruneCacheAction.java
└── package-info.java

server/src/main/java/org/opensearch/rest/action/admin/cluster/
└── RestPruneCacheAction.java

Files Modified

server/src/main/java/org/opensearch/action/ActionModule.java       # Action & REST handler registration
server/src/main/java/org/opensearch/node/Node.java                 # FileCache dependency injection
server/src/test/java/org/opensearch/action/ActionModuleTests.java  # Framework integration tests

Advanced Capabilities

Intelligent Node Targeting

# Target all warm nodes (default)
POST /_cache/filecache/prune

# Target specific warm nodes
POST /_cache/filecache/prune?nodes=warm-node-1,warm-node-2

# Target single node
POST /_cache/filecache/prune?node=warm-node-1

# With operation timeout
POST /_cache/filecache/prune?timeout=60s

Test Architecture

• PruneCacheRequestResponseTests.java
• TransportPruneCacheActionTests.java
• RestPruneCacheActionTests.java

Behavior Details

• Warm Nodes: Executes FileCache.prune() and returns actual freed bytes with capacity metrics
• Non-Warm Nodes: Safely filtered out.
• Null FileCache: Graceful handling returning zero metrics.
• Exception Handling: FileCache layer exceptions properly surfaced with node context

Sequence Flow Diagram

[github-actions]

❌ Gradle check result for 7788eb6: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

[gaobinlong]

Mind opening an issue to describe the purpose of this new API?

[x-INFiN1TY-x]

Gradle Check failed due to Flaky Tests : #17486

[github-actions]

❕ Gradle check result for 5f88ec4: UNSTABLE

Please review all flaky tests that succeeded after retry and create an issue if one does not already exist to track the flaky failure.

[codecov]

Codecov Report

❌ Patch coverage is 85.51724% with 21 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.07%. Comparing base (5468936) to head (e60f938).
⚠️ Report is 8 commits behind head on main.

Files with missing lines	Patch %	Lines
...uster/filecache/TransportPruneFileCacheAction.java	75.00%	7 Missing and 2 partials ⚠️
.../cluster/filecache/NodePruneFileCacheResponse.java	72.41%	8 Missing ⚠️
...dmin/cluster/filecache/PruneFileCacheResponse.java	93.61%	0 Missing and 3 partials ⚠️
...est/action/admin/cluster/RestPruneCacheAction.java	93.75%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main   #19321      +/-   ##
============================================
- Coverage     73.09%   73.07%   -0.02%     
- Complexity    70723    70791      +68     
============================================
  Files          5725     5731       +6     
  Lines        323796   323941     +145     
  Branches      46886    46901      +15     
============================================
+ Hits         236673   236725      +52     
- Misses        68009    68108      +99     
+ Partials      19114    19108       -6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

❌ Gradle check result for ca35f02: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

[github-actions]

✅ Gradle check result for 8fb90d0: SUCCESS

[x-INFiN1TY-x]

Requesting Review

CC : @Harsh-87

[Gagan6164]

Apart from these minor comments, rest of the changes LGTM.

[github-actions]

❌ Gradle check result for d288abf: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

[x-INFiN1TY-x]

Gradle Check failed due to Flaky Tests : #17486

[github-actions]

❕ Gradle check result for 3497d16: UNSTABLE

Please review all flaky tests that succeeded after retry and create an issue if one does not already exist to track the flaky failure.

[ajaymovva]

LGTM the changes I don't see any test that covers the actual prune of the file cache. If it was already covered that is ok if not can we add few IT's where we actually have the data in file cache and it get pruned after API trigger.

[github-actions]

✅ Gradle check result for f8c8093: SUCCESS

[github-actions]

✅ Gradle check result for e60f938: SUCCESS