feat: shell tool

docker/docker-compose.yml

@@ -0,0 +1,82 @@
+#
+# 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.
+#
+
+# Fluss local development cluster
+# Usage:
+#   docker compose -f docker/docker-compose.yml up -d
+#   docker compose -f docker/docker-compose.yml exec coordinator ./bin/fluss-database.sh --bootstrap-server coordinator:9123 --list
+
+services:
+  zookeeper:
+    image: zookeeper:3.8
+    ports:
+      - "2181:2181"
+    environment:
+      ZOO_MY_ID: 1
+
+  coordinator:
+    image: fluss-local
+    depends_on:
+      - zookeeper
+    ports:
+      - "9123:9123"
+    environment:
+      FLUSS_PROPERTIES: |
+        zookeeper.address: zookeeper:2181
+        bind.listeners: FLUSS://coordinator:9123
+        remote.data.dir: /tmp/fluss-remote-data
+    command: coordinatorServer
+
+  tablet-server-0:
+    image: fluss-local
+    depends_on:
+      - coordinator
+    environment:
+      FLUSS_PROPERTIES: |
+        zookeeper.address: zookeeper:2181
+        bind.listeners: FLUSS://tablet-server-0:9123
+        tablet-server.id: 0
+        data.dir: /tmp/fluss-data
+        remote.data.dir: /tmp/fluss-remote-data
+    command: tabletServer
+
+  tablet-server-1:
+    image: fluss-local
+    depends_on:
+      - coordinator
+    environment:
+      FLUSS_PROPERTIES: |
+        zookeeper.address: zookeeper:2181
+        bind.listeners: FLUSS://tablet-server-1:9123
+        tablet-server.id: 1
+        data.dir: /tmp/fluss-data
+        remote.data.dir: /tmp/fluss-remote-data
+    command: tabletServer
+
+  tablet-server-2:
+    image: fluss-local
+    depends_on:
+      - coordinator
+    environment:
+      FLUSS_PROPERTIES: |
+        zookeeper.address: zookeeper:2181
+        bind.listeners: FLUSS://tablet-server-2:9123
+        tablet-server.id: 2
+        data.dir: /tmp/fluss-data
+        remote.data.dir: /tmp/fluss-remote-data
+    command: tabletServer

fluss-cli/pom.xml

@@ -0,0 +1,70 @@
+<?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</artifactId>
+        <version>1.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>fluss-cli</artifactId>
+    <name>Fluss : CLI</name>
+    <packaging>jar</packaging>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.fluss</groupId>
+            <artifactId>fluss-client</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+
+        <dependency>
+            <groupId>commons-cli</groupId>
+            <artifactId>commons-cli</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+        </dependency>
+
+        <!-- Test -->
+        <dependency>
+            <groupId>org.apache.fluss</groupId>
+            <artifactId>fluss-test-utils</artifactId>
+            <version>${project.version}</version>
+            <scope>test</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

fluss-cli/src/main/java/org/apache/fluss/cli/CommandDefaultOptions.java

@@ -0,0 +1,117 @@
+/*
+ * 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.cli;
+
+import org.apache.fluss.annotation.Internal;
+
+import org.apache.commons.cli.CommandLine;
+import org.apache.commons.cli.DefaultParser;
+import org.apache.commons.cli.Option;
+import org.apache.commons.cli.Options;
+import org.apache.commons.cli.ParseException;
+
+import java.io.FileInputStream;
+import java.io.IOException;
+import java.util.Properties;
+
+/**
+ * Base class for CLI command option parsers. Provides common options shared by all CLI tools:
+ * {@code --help}, {@code --version}, {@code --bootstrap-server}, {@code --command-config}.
+ */
+@Internal
+public class CommandDefaultOptions {
+
+    private static final Option HELP_OPT =
+            Option.builder().longOpt("help").desc("Print usage information.").build();
+
+    private static final Option VERSION_OPT =
+            Option.builder().longOpt("version").desc("Display Fluss version.").build();
+
+    private static final Option BOOTSTRAP_SERVER_OPT =
+            Option.builder()
+                    .longOpt("bootstrap-server")
+                    .hasArg()
+                    .argName("server")
+                    .desc("REQUIRED: The Fluss server to connect to.")
+                    .build();
+
+    private static final Option COMMAND_CONFIG_OPT =
+            Option.builder()
+                    .longOpt("command-config")
+                    .hasArg()
+                    .argName("file")
+                    .desc("Property file containing configs to be passed to the client.")
+                    .build();
+
+    protected final Options options;
+    protected CommandLine commandLine;
+
+    protected CommandDefaultOptions() {
+        this.options = new Options();
+        options.addOption(HELP_OPT);
+        options.addOption(VERSION_OPT);
+        options.addOption(BOOTSTRAP_SERVER_OPT);
+        options.addOption(COMMAND_CONFIG_OPT);
+    }
+
+    protected void parse(String[] args) throws ParseException {
+        this.commandLine = new DefaultParser().parse(options, args);
+        if (!hasHelpOption() && !hasVersionOption() && bootstrapServer() == null) {
+            throw new ParseException("Missing required option: --bootstrap-server");
+        }
+    }
+
+    /** Returns {@code true} if the {@code --help} flag was specified. */
+    public boolean hasHelpOption() {
+        return commandLine.hasOption(HELP_OPT);
+    }
+
+    /** Returns {@code true} if the {@code --version} flag was specified. */
+    public boolean hasVersionOption() {
+        return commandLine.hasOption(VERSION_OPT);
+    }
+
+    /** Returns the value of {@code --bootstrap-server}, or {@code null} if not specified. */
+    public String bootstrapServer() {
+        return commandLine.getOptionValue(BOOTSTRAP_SERVER_OPT);
+    }
+
+    /**
+     * Loads the properties file specified by {@code --command-config}. Returns an empty {@link
+     * Properties} instance if the option was not specified.
+     */
+    public Properties commandConfig() {
+        Properties props = new Properties();
+        String file = commandLine.getOptionValue(COMMAND_CONFIG_OPT);
+        if (file == null) {
+            return props;
+        }
+        try (FileInputStream fis = new FileInputStream(file)) {
+            props.load(fis);
+        } catch (IOException e) {
+            throw new IllegalArgumentException("Failed to load command config file: " + file, e);
+        }
+        return props;
+    }
+
+    /** Returns the configured {@link Options} for generating help text. */
+    public Options options() {
+        return options;
+    }
+}

fluss-cli/src/main/java/org/apache/fluss/cli/CommandUtils.java

@@ -0,0 +1,109 @@
+/*
+ * 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.cli;
+
+import org.apache.fluss.annotation.Internal;
+import org.apache.fluss.client.Connection;
+import org.apache.fluss.client.ConnectionFactory;
+import org.apache.fluss.config.Configuration;
+
+import org.apache.commons.cli.CommandLine;
+import org.apache.commons.cli.HelpFormatter;
+import org.apache.commons.cli.Option;
+import org.apache.commons.cli.Options;
+
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Properties;
+import java.util.concurrent.ExecutionException;
+import java.util.stream.Collectors;
+
+/** Shared utility methods for CLI commands. */
+@Internal
+public final class CommandUtils {
+
+    public static final long DEFAULT_TIMEOUT_SECS = 30;
+
+    private CommandUtils() {}
+
+    /** Create a {@link Connection} from common CLI options. */
+    public static Connection createConnection(CommandDefaultOptions opts) {
+        Configuration conf = new Configuration();
+        conf.setString("bootstrap.servers", opts.bootstrapServer());
+        Properties cmdConfig = opts.commandConfig();
+        cmdConfig.forEach((k, v) -> conf.setString((String) k, (String) v));
+        return ConnectionFactory.createConnection(conf);
+    }
+
+    /** Validate exactly one action flag is specified. */
+    public static void validateActions(CommandLine cmd, Option... actions) {
+        long count = Arrays.stream(actions).filter(cmd::hasOption).count();
+        if (count != 1) {
+            String names =
+                    Arrays.stream(actions)
+                            .map(o -> "--" + o.getLongOpt())
+                            .collect(Collectors.joining(", "));
+            throw new IllegalArgumentException("Exactly one of " + names + " must be specified.");
+        }
+    }
+
+    /** Print help and exit. */
+    public static void printUsageAndExit(Options options, String cmdName) {
+        HelpFormatter formatter = new HelpFormatter();
+        formatter.setWidth(100);
+        formatter.printHelp(cmdName, options, true);
+        System.exit(0);
+    }
+
+    /** Print version and exit. */
+    public static void printVersionAndExit() {
+        String version = CommandUtils.class.getPackage().getImplementationVersion();
+        if (version == null) {
+            version = "(version unknown)";
+        }
+        System.out.println("Fluss CLI version " + version);
+        System.exit(0);
+    }
+
+    /** Parse repeatable {@code --property key=value} options into a Map. */
+    public static Map<String, String> parseProperties(String[] values) {
+        Map<String, String> props = new HashMap<>();
+        if (values == null) {
+            return props;
+        }
+        for (String prop : values) {
+            String[] kv = prop.split("=", 2);
+            if (kv.length != 2) {
+                throw new IllegalArgumentException(
+                        "Invalid property format: '" + prop + "'. Expected key=value.");
+            }
+            props.put(kv[0].trim(), kv[1].trim());
+        }
+        return props;
+    }
+
+    /** Unwrap {@link ExecutionException} to get the root cause message. */
+    public static String unwrapExceptionMessage(Throwable e) {
+        if (e instanceof ExecutionException && e.getCause() != null) {
+            return e.getCause().getMessage();
+        }
+        return e.getMessage();
+    }
+}