refactor!: use topics subcommand for topic management

BREAKING CHANGE: the existing subcommands belong to the topics command now

Author: BewareMyPower

CMakeLists.txt

@@ -33,11 +33,11 @@ if (SIMPLEINI_INCLUDE_DIRS)
 else ()
     message(FATAL_ERROR "SimpleIni not found")
 endif ()
-include_directories(${SIMPLEINI_INCLUDE_DIRS})
+include_directories("${CMAKE_SOURCE_DIR}/include" ${SIMPLEINI_INCLUDE_DIRS})
 
 find_package(RdKafka CONFIG REQUIRED)
 find_package(argparse CONFIG REQUIRED)
 
-add_executable(snctl-cpp main.cc)
+add_executable(snctl-cpp src/main.cc)
 target_compile_definitions(snctl-cpp PUBLIC VERSION_STR="${VERSION_STR}")
 target_link_libraries(snctl-cpp PRIVATE argparse::argparse RdKafka::rdkafka)

README.md

@@ -6,7 +6,9 @@ The CLI tool to manage clusters on StreamNative Cloud.
 
 ### (Recommended) Use pre-built binaries
 
-Currently the release only supports macOS 14 or later with arm64 architecture.
+Currently the release only supports
+- macOS 14 or later: arm64 architecture only
+- Alpine Linux 3.21 or later: amd64 or amd64 architecture
 
 Take v0.1.0 for example:
 
@@ -25,6 +27,10 @@ export PATH=$HOME/.snctl-cpp:$PATH
 
 Now, you can run `snctl-cpp -h` to see the help message.
 
+> **NOTE**:
+>
+> Actually running `./install.sh` is not necessary. You can run `./snctl-cpp` directly in the uncompressed directory because `sncloud.ini` is in the same directory.
+
 ### Build from source
 
 You must have a C++ compiler that supports C++17.
@@ -38,7 +44,7 @@ cp build/snctl-cpp .
 
 You can run `./install.sh` to override the existing installation in `~/.snctl-cpp` directory, but you can also just run `./snctl-cpp` directly without installing it. The `sncloud.ini` file in the current working directory has higher priority than the one in `~/.snctl-cpp` directory.
 
-## How to manage topics in the cluster that enables Kafka protocol
+## Configuration
 
 **Please make sure the `sncloud.ini` file is in the current working directory or `~/.snctl-cpp` directory if you don't specify the `--config` option.**
 
@@ -50,21 +56,25 @@ Options:
 - Add the `--config <config-file>` option to specify a different path of the INI config file.
 - Add a `--client-id` option to specify the client id of the underlying Kafka client. In Ursa, the client id carries the zone information, see [here](https://docs.streamnative.io/docs/config-kafka-client#eliminate-cross-az-networking-traffic).
 
+The built-in `sncloud.ini` file specifies `localhost:9092` as the default bootstrap server. You can also test `snctl-cpp` against a local Kafka cluster.
+
+## Commands
+
 ### Create a topic
 
 ```bash
-$ snctl-cpp create tp0
+$ snctl-cpp topics create tp0
 Created topic "tp0" with 1 partition
-$ snctl-cpp create tp1 -p 5
+$ snctl-cpp topics create tp1 -p 5
 Created topic "tp1" with 5 partitions
 ```
 
 ### Delete a topic
 
 ```bash
-$ snctl-cpp delete tp
+$ snctl-cpp topics delete tp
 Failed to delete topic "tp": Broker: Unknown topic or partition
-$ snctl-cpp delete tp0
+$ snctl-cpp topics delete tp0
 Deleted topic "tp0"
 ```
 
@@ -73,7 +83,7 @@ Deleted topic "tp0"
 Query the owner brokers for all partitions:
 
 ```bash
-$ snctl-cpp describe <topic>
+$ snctl-cpp topics describe <topic>
 Partition[0] leader: {"id": 816909419, url: "pb0-<xxx>:9093"}"
 Partition[1] leader: {"id": 101337027, url: "pb4-<xxx>:9093"}"
 ...
@@ -83,7 +93,7 @@ Partition[15] leader: {"id": 644587507, url: "pb2-<xxx>:9093"}"
 Query the owner brokers for all partitions in a specific zone (`use1-az1` in this case):
 
 ```bash
-$ snctl-cpp --client-id zone_id=use1-az1 describe <topic>
+$ snctl-cpp --client-id zone_id=use1-az1 topics describe <topic>
 Partition[0] leader: {"id": 1868363245, url: "pb5-<xxx>:9093"}
 Partition[1] leader: {"id": 1868363245, url: "pb5-<xxx>:9093"}
 ...
@@ -97,7 +107,7 @@ As you can see, when a client specifies `use1-az1` as its zone, only brokers in
 List all topics and print the number of partitions for each topic:
 
 ```bash
-$ snctl-cpp list
+$ snctl-cpp topics list
 topic count: 2
 [0] "my-topic-2" with 1 partition
 [1] "my-topic-1" with 10 partitions

rk_event_wrapper.h include/snctl-cpp/rk_event_wrapper.hrk_event_wrapper.h renamed to include/snctl-cpp/rk_event_wrapper.h

@@ -0,0 +1,87 @@
+/**
+ * Copyright 2025 Yunze Xu
+ *
+ * Licensed 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.
+ */
+#pragma once
+
+#include "snctl-cpp/topics/create_topic.h"
+#include "snctl-cpp/topics/delete_topic.h"
+#include "snctl-cpp/topics/describe_topic.h"
+#include "snctl-cpp/topics/list_topics.h"
+#include <argparse/argparse.hpp>
+#include <iostream>
+#include <librdkafka/rdkafka.h>
+
+class Topics {
+public:
+  Topics(argparse::ArgumentParser &parent) {
+    create_command_.add_description("Create a topic");
+    create_command_.add_argument("topic").help("Topic to create").required();
+    create_command_.add_argument("-p")
+        .help("Number of partitions")
+        .scan<'i', int>()
+        .default_value(1);
+
+    delete_command_.add_description("Delete a topic");
+    delete_command_.add_argument("topic").help("Topic to delete").required();
+
+    list_command_.add_description("List topics");
+
+    describe_command_.add_description("Describe a topic");
+    describe_command_.add_argument("topic")
+        .help("Topic to describe")
+        .required();
+
+    current_.add_subparser(create_command_);
+    current_.add_subparser(delete_command_);
+    current_.add_subparser(list_command_);
+    current_.add_subparser(describe_command_);
+
+    parent.add_subparser(current_);
+  }
+
+  bool run(rd_kafka_t *rk, rd_kafka_queue_t *rkqu) {
+    if (current_.is_subcommand_used(create_command_)) {
+      auto topic = create_command_.get("topic");
+      auto partitions = create_command_.get<int>("-p");
+      if (partitions < 0) {
+        throw std::invalid_argument(
+            "Number of partitions must be greater than or equal to 0");
+      }
+      create_topic(rk, rkqu, topic, partitions);
+    } else if (current_.is_subcommand_used(delete_command_)) {
+      auto topic = delete_command_.get("topic");
+      delete_topic(rk, rkqu, topic);
+    } else if (current_.is_subcommand_used(list_command_)) {
+      list_topics(rk);
+    } else if (current_.is_subcommand_used(describe_command_)) {
+      auto topic = describe_command_.get("topic");
+      describe_topic(rk, rkqu, topic);
+    } else {
+      std::cerr << "Invalid subcommand for topics\n" << current_ << std::endl;
+      return false;
+    }
+    return true;
+  }
+
+  auto &handle() const noexcept { return current_; }
+
+private:
+  argparse::ArgumentParser current_{"topics"};
+
+  argparse::ArgumentParser create_command_{"create"};
+  argparse::ArgumentParser delete_command_{"delete"};
+  argparse::ArgumentParser list_command_{"list"};
+  argparse::ArgumentParser describe_command_{"describe"};
+};

include/snctl-cpp/topics.h

@@ -15,7 +15,7 @@
  */
 #pragma once
 
-#include "rk_event_wrapper.h"
+#include "snctl-cpp/rk_event_wrapper.h"
 #include <array>
 #include <iostream>
 #include <librdkafka/rdkafka.h>

create_topic.h include/snctl-cpp/topics/create_topic.hcreate_topic.h renamed to include/snctl-cpp/topics/create_topic.h

@@ -15,7 +15,7 @@
  */
 #pragma once
 
-#include "rk_event_wrapper.h"
+#include "snctl-cpp/rk_event_wrapper.h"
 #include <iostream>
 #include <librdkafka/rdkafka.h>
 #include <memory>

delete_topic.h include/snctl-cpp/topics/delete_topic.hdelete_topic.h renamed to include/snctl-cpp/topics/delete_topic.h

@@ -15,7 +15,7 @@
  */
 #pragma once
 
-#include "rk_event_wrapper.h"
+#include "snctl-cpp/rk_event_wrapper.h"
 #include <iostream>
 #include <librdkafka/rdkafka.h>
 #include <stdexcept>

describe_topic.h include/snctl-cpp/topics/describe_topic.hdescribe_topic.h renamed to include/snctl-cpp/topics/describe_topic.h

@@ -14,23 +14,23 @@
  * limitations under the License.
  */
 #include "SimpleIni.h"
-#include "create_topic.h"
-#include "delete_topic.h"
-#include "describe_topic.h"
-#include "list_topics.h"
 #include <argparse/argparse.hpp>
 #include <array>
 #include <cstdio>
 #include <cstdlib>
 #include <cstring>
+#include <exception>
 #include <filesystem>
+#include <iostream>
 #include <librdkafka/rdkafka.h>
 #include <memory>
 #include <stdexcept>
 #include <string>
 #include <type_traits>
 #include <vector>
 
+#include "snctl-cpp/topics.h"
+
 int main(int argc, char *argv[]) {
   std::vector<std::string> default_config_paths{
       std::filesystem::current_path() / "sncloud.ini",
@@ -49,30 +49,14 @@ int main(int argc, char *argv[]) {
       .help("Path to the config file");
   program.add_argument("--client-id").help("client id");
 
-  argparse::ArgumentParser describe_command("describe");
-  describe_command.add_description("Describe a topic");
-  describe_command.add_argument("topic").help("Topic to describe").required();
-  program.add_subparser(describe_command);
-
-  argparse::ArgumentParser list_command("list");
-  list_command.add_description("List topics");
-  program.add_subparser(list_command);
-
-  argparse::ArgumentParser create_command("create");
-  create_command.add_description("Create a topic");
-  create_command.add_argument("topic").help("Topic to create").required();
-  create_command.add_argument("-p")
-      .help("Number of partitions")
-      .scan<'i', int>()
-      .default_value(1);
-  program.add_subparser(create_command);
-
-  argparse::ArgumentParser delete_command("delete");
-  delete_command.add_description("Delete a topic");
-  delete_command.add_argument("topic").help("Topic to delete").required();
-  program.add_subparser(delete_command);
-
-  program.parse_args(argc, argv);
+  Topics topics{program};
+  try {
+    program.parse_args(argc, argv);
+  } catch (const std::exception &err) {
+    std::cerr << "Failed to parse args: " << err.what() << "\n"
+              << program << std::endl;
+    return 1;
+  }
 
   auto rk_conf = rd_kafka_conf_new();
 
@@ -162,23 +146,11 @@ int main(int argc, char *argv[]) {
                   decltype(&rd_kafka_queue_destroy)>
       rkque_guard{rkqu, &rd_kafka_queue_destroy};
 
-  if (program.is_subcommand_used(describe_command)) {
-    describe_topic(rk, rkqu, describe_command.get("topic"));
-  } else if (program.is_subcommand_used(list_command)) {
-    list_topics(rk);
-  } else if (program.is_subcommand_used(create_command)) {
-    auto topic = create_command.get("topic");
-    auto partitions = create_command.get<int>("-p");
-    if (partitions < 0) {
-      throw std::invalid_argument(
-          "Number of partitions must be greater than or equal to 0");
-    }
-    create_topic(rk, rkqu, topic, partitions);
-  } else if (program.is_subcommand_used(delete_command)) {
-    auto topic = delete_command.get("topic");
-    delete_topic(rk, rkqu, topic);
+  if (program.is_subcommand_used(topics.handle())) {
+    topics.run(rk, rkqu);
   } else {
-    throw std::runtime_error("Only describe command is supported");
+    std::cerr << "Invalid subcommand\n" << program << std::endl;
+    return 1;
   }
 
   return 0;