[flink-action][server][client] add orphan files cleanup action for remote storage

fluss-client/src/main/java/org/apache/fluss/client/admin/Admin.java

@@ -17,6 +17,7 @@
 
 package org.apache.fluss.client.admin;
 
+import org.apache.fluss.annotation.Internal;
 import org.apache.fluss.annotation.PublicEvolving;
 import org.apache.fluss.client.metadata.KvSnapshotMetadata;
 import org.apache.fluss.client.metadata.KvSnapshots;
@@ -67,6 +68,8 @@
 import org.apache.fluss.metadata.TableInfo;
 import org.apache.fluss.metadata.TablePath;
 import org.apache.fluss.metadata.TableStats;
+import org.apache.fluss.rpc.messages.ListKvSnapshotsResponse;
+import org.apache.fluss.rpc.messages.ListRemoteLogManifestsResponse;
 import org.apache.fluss.security.acl.AclBinding;
 import org.apache.fluss.security.acl.AclBindingFilter;
 
@@ -770,4 +773,32 @@ CompletableFuture<RegisterResult> registerProducerOffsets(
      * @since 0.9
      */
     CompletableFuture<Void> deleteProducerOffsets(String producerId);
+
+    /**
+     * List per-bucket remote log manifest entries for a table or partition scope.
+     *
+     * @param tableId the table to query
+     * @param partitionId optional partition id (null for non-partitioned tables)
+     * @return per-bucket manifest paths and end offsets
+     */
+    @Internal
+    default CompletableFuture<ListRemoteLogManifestsResponse> listRemoteLogManifests(
+            long tableId, @Nullable Long partitionId) {
+        throw new UnsupportedOperationException(
+                "listRemoteLogManifests is not supported by this Admin implementation");
+    }
+
+    /**
+     * List per-bucket active KV snapshot ids for a table or partition scope.
+     *
+     * @param tableId the table to query
+     * @param partitionId optional partition id (null for non-partitioned tables)
+     * @return per-bucket active snapshot entries
+     */
+    @Internal
+    default CompletableFuture<ListKvSnapshotsResponse> listKvSnapshots(
+            long tableId, @Nullable Long partitionId) {
+        throw new UnsupportedOperationException(
+                "listKvSnapshots is not supported by this Admin implementation");
+    }
 }

fluss-client/src/main/java/org/apache/fluss/client/admin/FlussAdmin.java

@@ -79,10 +79,14 @@
 import org.apache.fluss.rpc.messages.ListAclsRequest;
 import org.apache.fluss.rpc.messages.ListDatabasesRequest;
 import org.apache.fluss.rpc.messages.ListDatabasesResponse;
+import org.apache.fluss.rpc.messages.ListKvSnapshotsRequest;
+import org.apache.fluss.rpc.messages.ListKvSnapshotsResponse;
 import org.apache.fluss.rpc.messages.ListOffsetsRequest;
 import org.apache.fluss.rpc.messages.ListOffsetsResponse;
 import org.apache.fluss.rpc.messages.ListPartitionInfosRequest;
 import org.apache.fluss.rpc.messages.ListRebalanceProgressRequest;
+import org.apache.fluss.rpc.messages.ListRemoteLogManifestsRequest;
+import org.apache.fluss.rpc.messages.ListRemoteLogManifestsResponse;
 import org.apache.fluss.rpc.messages.ListTablesRequest;
 import org.apache.fluss.rpc.messages.ListTablesResponse;
 import org.apache.fluss.rpc.messages.PbAlterConfig;
@@ -367,6 +371,38 @@ public CompletableFuture<List<PartitionInfo>> listPartitionInfos(
                 .thenApply(ClientRpcMessageUtils::toPartitionInfos);
     }
 
+    /**
+     * Returns per-bucket remote log manifest path for the given table or partition.
+     *
+     * <p>Used by the orphan cleanup action to construct the active manifest path set without
+     * relying on FS LIST + mtime selection.
+     */
+    @Override
+    public CompletableFuture<ListRemoteLogManifestsResponse> listRemoteLogManifests(
+            long tableId, @Nullable Long partitionId) {
+        ListRemoteLogManifestsRequest request = new ListRemoteLogManifestsRequest();
+        request.setTableId(tableId);
+        if (partitionId != null) {
+            request.setPartitionId(partitionId);
+        }
+        return gateway.listRemoteLogManifests(request);
+    }
+
+    /**
+     * Returns per-bucket active KV snapshot dirs (retained_N + still-in-use) for the given table or
+     * partition. Used by the orphan cleanup action to construct the complete KV active set.
+     */
+    @Override
+    public CompletableFuture<ListKvSnapshotsResponse> listKvSnapshots(
+            long tableId, @Nullable Long partitionId) {
+        ListKvSnapshotsRequest request = new ListKvSnapshotsRequest();
+        request.setTableId(tableId);
+        if (partitionId != null) {
+            request.setPartitionId(partitionId);
+        }
+        return gateway.listKvSnapshots(request);
+    }
+
     @Override
     public CompletableFuture<Void> createPartition(
             TablePath tablePath, PartitionSpec partitionSpec, boolean ignoreIfExists) {

fluss-client/src/main/java/org/apache/fluss/client/utils/ClientRpcMessageUtils.java

@@ -533,6 +533,17 @@ public static ReleaseKvSnapshotLeaseRequest makeReleaseKvSnapshotLeaseRequest(
         return request;
     }
 
+    public static PbTableBucket toPbTableBucket(TableBucket tableBucket) {
+        PbTableBucket pbTableBucket =
+                new PbTableBucket()
+                        .setTableId(tableBucket.getTableId())
+                        .setBucketId(tableBucket.getBucket());
+        if (tableBucket.getPartitionId() != null) {
+            pbTableBucket.setPartitionId(tableBucket.getPartitionId());
+        }
+        return pbTableBucket;
+    }
+
     public static Optional<RebalanceProgress> toRebalanceProgress(
             ListRebalanceProgressResponse response) {
         if (!response.hasRebalanceId()) {

fluss-common/src/main/java/org/apache/fluss/fs/FileStatus.java

@@ -46,4 +46,18 @@ public interface FileStatus {
      * @return the corresponding Path to the FileStatus
      */
     FsPath getPath();
+
+    /**
+     * Returns the modification time of the file in milliseconds since the epoch.
+     *
+     * <p>The default implementation returns {@link Long#MAX_VALUE}, which is interpreted by
+     * time-based filters (e.g. orphan-files cleanup) as "always fresh" - effectively a fail-closed
+     * default that prevents deletion when modification time is unavailable. File system
+     * implementations that can expose modification time SHOULD override this.
+     *
+     * @return the modification time in epoch millis, or {@link Long#MAX_VALUE} when unavailable
+     */
+    default long getModificationTime() {
+        return Long.MAX_VALUE;
+    }
 }

fluss-common/src/main/java/org/apache/fluss/fs/local/LocalFileStatus.java

@@ -67,6 +67,11 @@ public FsPath getPath() {
         return this.path;
     }
 
+    @Override
+    public long getModificationTime() {
+        return this.file.lastModified();
+    }
+
     public File getFile() {
         return this.file;
     }

fluss-common/src/main/java/org/apache/fluss/utils/FlussPaths.java

@@ -74,7 +74,7 @@ public class FlussPaths {
     public static final String REMOTE_LOG_DIR_NAME = "log";
 
     /** The directory name for storing metadata files (e.g., manifest) for a log tablet. */
-    private static final String REMOTE_LOG_METADATA_DIR_NAME = "metadata";
+    public static final String REMOTE_LOG_METADATA_DIR_NAME = "metadata";
 
     /** Suffix of a manifest file. */
     private static final String REMOTE_LOG_MANIFEST_FILE_SUFFIX = ".manifest";

fluss-filesystems/fluss-fs-hadoop/src/main/java/org/apache/fluss/fs/hdfs/HadoopFileStatus.java

@@ -52,6 +52,11 @@ public boolean isDir() {
         return fileStatus.isDirectory();
     }
 
+    @Override
+    public long getModificationTime() {
+        return fileStatus.getModificationTime();
+    }
+
     // ------------------------------------------------------------------------
 
     /**

fluss-flink/fluss-flink-action/pom.xml

@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>org.apache.fluss</groupId>
+        <artifactId>fluss-flink</artifactId>
+        <version>1.0-SNAPSHOT</version>
+    </parent>
+
+    <packaging>jar</packaging>
+
+    <artifactId>fluss-flink-action</artifactId>
+    <name>Fluss : Flink : Action</name>
+
+    <properties>
+        <flink.minor.version>1.20.3</flink.minor.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.fluss</groupId>
+            <artifactId>fluss-flink-common</artifactId>
+            <version>${project.version}</version>
+            <scope>provided</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.apache.flink</groupId>
+            <artifactId>flink-streaming-java</artifactId>
+            <version>${flink.minor.version}</version>
+            <scope>provided</scope>
+        </dependency>
+    </dependencies>
+
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-shade-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>shade-fluss</id>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>shade</goal>
+                        </goals>
+                        <configuration>
+                            <transformers>
+                                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+                                    <mainClass>org.apache.fluss.flink.action.FlussFlinkActionEntrypoint</mainClass>
+                                </transformer>
+                                <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
+                            </transformers>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+
+        </plugins>
+    </build>
+</project>

fluss-flink/fluss-flink-action/src/main/java/org/apache/fluss/flink/action/FlussFlinkActionEntrypoint.java

@@ -0,0 +1,40 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.fluss.flink.action;
+
+import java.util.Optional;
+
+/** Main entrypoint for the Fluss Flink action jar. Delegates to {@link ActionLoader}. */
+public class FlussFlinkActionEntrypoint {
+
+    public static void main(String[] args) throws Exception {
+        Optional<Action> action;
+        try {
+            action = ActionLoader.createAction(args);
+        } catch (IllegalArgumentException e) {
+            System.err.println(e.getMessage());
+            System.exit(1);
+            return;
+        }
+        if (!action.isPresent()) {
+            return;
+        }
+        action.get().build();
+        action.get().run();
+    }
+}

fluss-flink/fluss-flink-common/src/main/java/org/apache/fluss/flink/action/Action.java

@@ -0,0 +1,31 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.fluss.flink.action;
+
+import org.apache.fluss.annotation.Internal;
+
+/** Pluggable Flink action invoked from CLI via {@link FlussFlinkActionEntrypoint}. */
+@Internal
+public interface Action {
+
+    /** Optional setup hook called once before {@link #run()}. */
+    default void build() throws Exception {}
+
+    /** Execute the action. */
+    void run() throws Exception;
+}

fluss-flink/fluss-flink-common/src/main/java/org/apache/fluss/flink/action/ActionFactory.java

@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.fluss.flink.action;
+
+import org.apache.fluss.annotation.Internal;
+
+import org.apache.flink.api.java.utils.MultipleParameterTool;
+
+import java.util.Optional;
+
+/** SPI for {@link Action} factories, registered via JDK {@link java.util.ServiceLoader}. */
+@Internal
+public interface ActionFactory {
+
+    /**
+     * Identifier matched against the first CLI argument after lowercasing and replacing {@code -}
+     * with {@code _}.
+     */
+    String identifier();
+
+    /** Construct the action from parsed CLI parameters. Empty when {@code --help} is requested. */
+    Optional<Action> create(MultipleParameterTool params);
+
+    /** Help text printed when {@code --help} is passed. */
+    default String help() {
+        return "";
+    }
+}