# MTranServer ROS2 English-to-Chinese Service Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Build a ROS2 Humble C++ service under `migrate_ws` that accepts one English string, translates it through a launch-managed persistent MTranServer, and returns Simplified Chinese. **Architecture:** A C++ `mtran_bridge_node` exposes `/translate_en_to_zh` and sends fixed `en -> zh-Hans` JSON requests to a loopback MTranServer sidecar. ROS2 launch owns both processes; the bridge performs startup health checking, model warm-up, serialized request handling, and periodic keep-warm calls. **Tech Stack:** ROS2 Humble, Ubuntu 22.04, C++17, ament_cmake, rosidl, libcurl, nlohmann/json, GoogleTest, Python ROS2 launch, Bun-compiled MTranServer. ## Global Constraints - Every new or generated migration file must remain under `/home/hikos/MTranServer/migrate_ws`. - The service name is `/translate_en_to_zh`. - The service request contains only `string text`. - The response contains `bool success`, `string translation`, and `string error`. - Translation direction is fixed to `en -> zh-Hans`; HTML, language detection, topics, batching, and retries are excluded. - Input is limited to 512 UTF-8 code points. - Translation execution is serialized with `rclcpp::executors::SingleThreadedExecutor`. - The current machine uses a native MTranServer build; ARM64 is documented but not built in this iteration. - MTranServer uses a 86,400-second idle timeout and the bridge sends a keep-warm translation every 43,200 seconds. - Runtime translation must work offline after the executable and `en_zh-Hans` model are staged. --- ## File Map - `migrate_ws/.gitignore`: excludes colcon output, local tools, runtime binary, temporary runtime build tree, and model data. - `migrate_ws/src/mtran_ros2/package.xml`: ROS2 and system dependency metadata. - `migrate_ws/src/mtran_ros2/CMakeLists.txt`: service generation, C++ targets, install rules, and tests. - `migrate_ws/src/mtran_ros2/srv/TranslateEnglishToChinese.srv`: public ROS2 interface. - `migrate_ws/src/mtran_ros2/include/mtran_ros2/http_translation_client.hpp`: transport-independent client contract and libcurl client declaration. - `migrate_ws/src/mtran_ros2/src/http_translation_client.cpp`: fixed HTTP payload, libcurl transport, JSON parsing, and error mapping. - `migrate_ws/src/mtran_ros2/include/mtran_ros2/translator_node.hpp`: node state and service declaration. - `migrate_ws/src/mtran_ros2/src/translator_node.cpp`: readiness state machine, validation, service callback, recovery, and keep-warm. - `migrate_ws/src/mtran_ros2/src/main.cpp`: ROS2 initialization and single-threaded spin. - `migrate_ws/src/mtran_ros2/config/translator.yaml`: production parameter defaults. - `migrate_ws/src/mtran_ros2/launch/translator.launch.py`: sidecar and bridge lifecycle. - `migrate_ws/src/mtran_ros2/scripts/build_mtranserver.sh`: native sidecar staging entirely below `migrate_ws`. - `migrate_ws/src/mtran_ros2/test/test_http_translation_client.cpp`: injected-transport unit tests. - `migrate_ws/src/mtran_ros2/test/test_translator_node.cpp`: fake-client ROS2 service tests. - `migrate_ws/README.md`: dependency, local build, launch, smoke-test, offline-model, and ARM64 instructions. --- ### Task 1: Create the ROS2 Package and Service Contract **Files:** - Create: `migrate_ws/.gitignore` - Create: `migrate_ws/src/mtran_ros2/package.xml` - Create: `migrate_ws/src/mtran_ros2/CMakeLists.txt` - Create: `migrate_ws/src/mtran_ros2/srv/TranslateEnglishToChinese.srv` **Interfaces:** - Consumes: ROS2 Humble `ament_cmake` and `rosidl_default_generators`. - Produces: `mtran_ros2::srv::TranslateEnglishToChinese` with request field `text` and response fields `success`, `translation`, and `error`. - [ ] **Step 1: Record generated-file exclusions** ```gitignore build/ install/ log/ .tools/ .runtime-build/ runtime/bin/mtranserver models/** !models/.gitkeep ``` - [ ] **Step 2: Write the service definition** ```srv string text --- bool success string translation string error ``` - [ ] **Step 3: Add the minimal package manifest** Declare `ament_cmake`, `rosidl_default_generators`, `rclcpp`, `rosidl_default_runtime`, `launch`, `launch_ros`, libcurl, nlohmann/json, and test dependencies. Add membership in `rosidl_interface_packages`. - [ ] **Step 4: Add interface generation to CMake** ```cmake cmake_minimum_required(VERSION 3.8) project(mtran_ros2) find_package(ament_cmake REQUIRED) find_package(rosidl_default_generators REQUIRED) rosidl_generate_interfaces(${PROJECT_NAME} "srv/TranslateEnglishToChinese.srv" ) ament_export_dependencies(rosidl_default_runtime) ament_package() ``` - [ ] **Step 5: Build to verify service generation** Run: ```bash source /opt/ros/humble/setup.bash cd /home/hikos/MTranServer/migrate_ws colcon build --packages-select mtran_ros2 ``` Expected: exit code 0 and generated service headers below `build/mtran_ros2/rosidl_generator_cpp`. - [ ] **Step 6: Inspect the generated interface** Run: ```bash source /home/hikos/MTranServer/migrate_ws/install/setup.bash ros2 interface show mtran_ros2/srv/TranslateEnglishToChinese ``` Expected: the exact four fields from the `.srv` definition. - [ ] **Step 7: Commit the package contract** ```bash git add migrate_ws/.gitignore migrate_ws/src/mtran_ros2/package.xml \ migrate_ws/src/mtran_ros2/CMakeLists.txt \ migrate_ws/src/mtran_ros2/srv/TranslateEnglishToChinese.srv git commit -m "feat: add ROS2 translation service contract" ``` --- ### Task 2: Implement the Fixed-Direction HTTP Client **Files:** - Create: `migrate_ws/src/mtran_ros2/include/mtran_ros2/http_translation_client.hpp` - Create: `migrate_ws/src/mtran_ros2/src/http_translation_client.cpp` - Create: `migrate_ws/src/mtran_ros2/test/test_http_translation_client.cpp` - Modify: `migrate_ws/src/mtran_ros2/CMakeLists.txt` - Modify: `migrate_ws/src/mtran_ros2/package.xml` **Interfaces:** - Consumes: `server_url` and `request_timeout_ms` configuration. - Produces: `TranslationClient::health()` and `TranslationClient::translate(const std::string&)`. Use these exact public types: ```cpp enum class ClientError { kNone, kUnavailable, kTimeout, kUpstream, kInvalidResponse, }; struct TranslationResult { bool success; std::string translation; ClientError error; }; struct HttpResponse { int transport_code; long status_code; std::string body; }; using HttpExecutor = std::function; class TranslationClient { public: virtual ~TranslationClient() = default; virtual bool health() = 0; virtual TranslationResult translate(const std::string & text) = 0; }; class HttpTranslationClient final : public TranslationClient { public: HttpTranslationClient( std::string server_url, long timeout_ms, HttpExecutor executor = {}); bool health() override; TranslationResult translate(const std::string & text) override; }; ``` - [ ] **Step 1: Write failing payload and parsing tests** Inject an `HttpExecutor` lambda that captures method, URL, body, and timeout. Assert that `translate("Hello")` sends `POST`, targets `/translate`, uses the configured timeout, and emits: ```json {"from":"en","html":false,"text":"Hello","to":"zh-Hans"} ``` Also assert that HTTP 200 with `{"result":"你好"}` returns `success=true`, `translation="你好"`, and `ClientError::kNone`. - [ ] **Step 2: Write failing error-mapping tests** Add separate tests for: ```cpp HttpResponse{CURLE_COULDNT_CONNECT, 0, ""} // kUnavailable HttpResponse{CURLE_OPERATION_TIMEDOUT, 0, ""} // kTimeout HttpResponse{CURLE_OK, 500, "failure"} // kUpstream HttpResponse{CURLE_OK, 200, "not-json"} // kInvalidResponse HttpResponse{CURLE_OK, 200, R"({"result":7})"} // kInvalidResponse ``` For every failure, assert `success=false` and `translation.empty()`. - [ ] **Step 3: Run the client test to verify it fails** Run: ```bash source /opt/ros/humble/setup.bash cd /home/hikos/MTranServer/migrate_ws colcon test --packages-select mtran_ros2 --ctest-args -R test_http_translation_client --output-on-failure ``` Expected: test target or referenced client types are missing. - [ ] **Step 4: Implement `HttpTranslationClient`** Use nlohmann/json to serialize the fixed request and parse `result`. Normalize `server_url` by removing trailing slashes. The default executor initializes libcurl once with `std::call_once`, writes response bytes through a callback, sets `CURLOPT_CONNECTTIMEOUT_MS`, `CURLOPT_TIMEOUT_MS`, JSON content type, and `CURLOPT_NOSIGNAL=1L`. Map libcurl connection and name-resolution failures to `kUnavailable`, `CURLE_OPERATION_TIMEDOUT` to `kTimeout`, other transport/non-200 failures to `kUpstream`, and response-shape failures to `kInvalidResponse`. - [ ] **Step 5: Add the client library and test targets** ```cmake find_package(CURL REQUIRED) find_package(nlohmann_json REQUIRED) find_package(rclcpp REQUIRED) add_library(mtran_core src/http_translation_client.cpp ) target_compile_features(mtran_core PUBLIC cxx_std_17) target_include_directories(mtran_core PUBLIC $ $) target_link_libraries(mtran_core PUBLIC CURL::libcurl nlohmann_json::nlohmann_json) ``` Under `BUILD_TESTING`, add `ament_cmake_gtest`, create `test_http_translation_client`, and link it to `mtran_core`. - [ ] **Step 6: Run the client tests** Run: ```bash source /opt/ros/humble/setup.bash cd /home/hikos/MTranServer/migrate_ws colcon build --packages-select mtran_ros2 --cmake-args -DBUILD_TESTING=ON colcon test --packages-select mtran_ros2 --ctest-args -R test_http_translation_client --output-on-failure colcon test-result --verbose ``` Expected: all client tests pass. - [ ] **Step 7: Commit the HTTP client** ```bash git add migrate_ws/src/mtran_ros2 git commit -m "feat: add fixed-direction MTran HTTP client" ``` --- ### Task 3: Implement the ROS2 Service Node and Readiness State Machine **Files:** - Create: `migrate_ws/src/mtran_ros2/include/mtran_ros2/translator_node.hpp` - Create: `migrate_ws/src/mtran_ros2/src/translator_node.cpp` - Create: `migrate_ws/src/mtran_ros2/src/main.cpp` - Create: `migrate_ws/src/mtran_ros2/test/test_translator_node.cpp` - Modify: `migrate_ws/src/mtran_ros2/CMakeLists.txt` **Interfaces:** - Consumes: `std::shared_ptr` and generated `TranslateEnglishToChinese` service type. - Produces: `/translate_en_to_zh`, startup/recovery health polling, warm-up, validation, and keep-warm behavior. Use this constructor boundary: ```cpp class TranslatorNode : public rclcpp::Node { public: explicit TranslatorNode( const rclcpp::NodeOptions & options = rclcpp::NodeOptions(), std::shared_ptr client = nullptr); }; ``` - [ ] **Step 1: Write the fake client and failing validation tests** Create a thread-safe fake implementing `TranslationClient`. Configure node parameter overrides `health_retry_ms=1`, `keep_warm_interval_s=3600`, and `max_input_characters=512`. Spin the node until `/translate_en_to_zh` is available. Assert: ```text "" and " " -> INVALID_INPUT 512 ASCII characters -> client called and success returned 513 ASCII characters -> INPUT_TOO_LONG and client not called ``` - [ ] **Step 2: Write failing response-mapping tests** For each fake client result, assert these exact service responses: ```text kNone -> success=true, translation set, error empty kUnavailable -> success=false, translation empty, NOT_READY kTimeout -> success=false, translation empty, TIMEOUT kUpstream -> success=false, translation empty, UPSTREAM_ERROR kInvalidResponse -> success=false, translation empty, INVALID_RESPONSE ``` - [ ] **Step 3: Write failing readiness and recovery tests** Verify that the service is not created while `health()` is false. Then switch health to true and make the warm-up translation succeed; verify the service becomes available. Simulate `kUnavailable` during a service call, verify `NOT_READY`, restore the fake, and verify health polling plus warm-up return the node to successful service operation. - [ ] **Step 4: Run node tests to verify failure** Run: ```bash source /opt/ros/humble/setup.bash cd /home/hikos/MTranServer/migrate_ws colcon test --packages-select mtran_ros2 --ctest-args -R test_translator_node --output-on-failure ``` Expected: `TranslatorNode` and executable are missing. - [ ] **Step 5: Implement startup, service, and recovery** Declare the six parameters from the design. When no client is injected, construct `HttpTranslationClient`. Start a health timer immediately. A successful health call followed by `translate("Hello.")` sets `ready_=true`, creates the service on first startup, cancels health polling, and starts keep-warm scheduling. Count UTF-8 characters by counting bytes that are not continuation bytes (`(byte & 0xC0) != 0x80`). Validate before checking readiness. Serialize all callbacks through the single-threaded executor. If a service or keep-warm call returns `kUnavailable`, set `ready_=false` and restart health polling. Do not destroy the already-advertised service after initial startup; requests during recovery return `NOT_READY`. - [ ] **Step 6: Implement `main.cpp`** ```cpp int main(int argc, char ** argv) { rclcpp::init(argc, argv); auto node = std::make_shared(); rclcpp::executors::SingleThreadedExecutor executor; executor.add_node(node); executor.spin(); rclcpp::shutdown(); return 0; } ``` - [ ] **Step 7: Add node targets and generated typesupport linkage** Add `translator_node.cpp` to `mtran_core`, obtain the generated C++ typesupport target with `rosidl_get_typesupport_target`, and link it. Add `mtran_bridge_node` from `main.cpp`, link `mtran_core`, and install the library, executable, and headers. - [ ] **Step 8: Run node and client tests** Run: ```bash source /opt/ros/humble/setup.bash cd /home/hikos/MTranServer/migrate_ws colcon build --packages-select mtran_ros2 --cmake-args -DBUILD_TESTING=ON colcon test --packages-select mtran_ros2 --event-handlers console_direct+ colcon test-result --verbose ``` Expected: all tests pass with no failed test cases. - [ ] **Step 9: Commit the ROS2 node** ```bash git add migrate_ws/src/mtran_ros2 git commit -m "feat: expose persistent English to Chinese ROS2 service" ``` --- ### Task 4: Add Native Runtime Staging and ROS2 Launch **Files:** - Create: `migrate_ws/src/mtran_ros2/config/translator.yaml` - Create: `migrate_ws/src/mtran_ros2/launch/translator.launch.py` - Create: `migrate_ws/src/mtran_ros2/scripts/build_mtranserver.sh` - Create: `migrate_ws/models/.gitkeep` - Modify: `migrate_ws/src/mtran_ros2/CMakeLists.txt` **Interfaces:** - Consumes: repository MTranServer source, local npm/node, launch arguments, staged executable, and staged model directory. - Produces: native `migrate_ws/runtime/bin/mtranserver` and one launch entry point that owns sidecar and bridge lifecycles. - [ ] **Step 1: Write the production parameter file** ```yaml mtran_bridge_node: ros__parameters: server_url: "http://127.0.0.1:8989" request_timeout_ms: 30000 startup_timeout_ms: 60000 health_retry_ms: 500 keep_warm_interval_s: 43200 max_input_characters: 512 ``` - [ ] **Step 2: Write the runtime staging script** The script resolves the repository root from its own path, installs Bun locally with npm under `migrate_ws/.tools` when no usable local Bun exists, copies the MTranServer source into `migrate_ws/.runtime-build/mtranserver` while excluding `.git`, `migrate_ws`, `node_modules`, and generated outputs, runs `bun install --frozen-lockfile`, runs `bun run build --single`, and installs the executable at `migrate_ws/runtime/bin/mtranserver` with mode 0755. The script must use `set -euo pipefail`, must not write to `/usr/local`, and must not modify the repository's root `dist/` directory. - [ ] **Step 3: Run the staging script** Run: ```bash cd /home/hikos/MTranServer ./migrate_ws/src/mtran_ros2/scripts/build_mtranserver.sh file migrate_ws/runtime/bin/mtranserver ``` Expected on the current machine: an executable x86-64 ELF MTranServer binary. - [ ] **Step 4: Write the launch file** Declare arguments `server_executable`, `model_dir`, `config_dir`, `params_file`, `host`, and `port`. Defaults resolve from the source workspace for local development and may be overridden for installed deployment. Start MTranServer with `ExecuteProcess` using: ```text MT_HOST= MT_PORT= MT_ENABLE_UI=false MT_OFFLINE=true MT_CHECK_UPDATE=false MT_CONFIG_DIR= MT_MODEL_DIR= MT_WORKER_IDLE_TIMEOUT=86400 MT_CACHE_SIZE=100 ``` Enable sidecar respawn with a 2-second delay. Start `mtran_bridge_node` with the parameter file and a `server_url` override derived from host and port. - [ ] **Step 5: Add launch syntax test and install rules** Run: ```bash python3 -m py_compile migrate_ws/src/mtran_ros2/launch/translator.launch.py ``` Expected: exit code 0. Install `launch/`, `config/`, and `scripts/` into the package share/lib destinations through CMake. - [ ] **Step 6: Verify launch description without starting translation** Run: ```bash source /opt/ros/humble/setup.bash cd /home/hikos/MTranServer/migrate_ws colcon build --packages-select mtran_ros2 source install/setup.bash ros2 launch mtran_ros2 translator.launch.py --show-args ``` Expected: all six launch arguments are listed with concrete defaults. - [ ] **Step 7: Commit runtime and launch support** ```bash git add migrate_ws/.gitignore migrate_ws/models/.gitkeep \ migrate_ws/src/mtran_ros2/config \ migrate_ws/src/mtran_ros2/launch \ migrate_ws/src/mtran_ros2/scripts \ migrate_ws/src/mtran_ros2/CMakeLists.txt git commit -m "feat: launch persistent MTran sidecar" ``` --- ### Task 5: Document, Stage the Model, and Verify End to End **Files:** - Create: `migrate_ws/README.md` - Modify only if verification finds a defect: files below `migrate_ws/src/mtran_ros2/` **Interfaces:** - Consumes: built native sidecar, ROS2 package, and `en_zh-Hans` model files. - Produces: reproducible local and ARM64 instructions plus evidence that automated and available runtime checks pass. - [ ] **Step 1: Write the README** Document: - Architecture and fixed service contract - Ubuntu 22.04/ROS2 Humble dependencies - Native runtime staging command - How to pre-download/copy only `en_zh-Hans` model files - `colcon build`, launch, and service-call commands - Error-code table - Offline operation and model residency behavior - x64 native build behavior - ARM64 native build and `bun-linux-arm64` cross-target commands - How to override executable and model paths at launch - [ ] **Step 2: Run formatting and static build checks** Run: ```bash source /opt/ros/humble/setup.bash cd /home/hikos/MTranServer/migrate_ws colcon build --packages-select mtran_ros2 --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_TESTING=ON colcon test --packages-select mtran_ros2 --event-handlers console_direct+ colcon test-result --verbose python3 -m py_compile src/mtran_ros2/launch/translator.launch.py ``` Expected: build and tests exit 0; Python compilation produces no output. - [ ] **Step 3: Check the staged runtime and model prerequisites** Run: ```bash test -x /home/hikos/MTranServer/migrate_ws/runtime/bin/mtranserver find /home/hikos/MTranServer/migrate_ws/models/en_zh-Hans -maxdepth 1 -type f -print ``` Expected: executable check passes and the model directory contains model, vocabulary, and lexical files required by MTranServer. - [ ] **Step 4: Start launch and execute the smoke test** Terminal 1: ```bash source /opt/ros/humble/setup.bash source /home/hikos/MTranServer/migrate_ws/install/setup.bash ros2 launch mtran_ros2 translator.launch.py ``` Terminal 2: ```bash source /opt/ros/humble/setup.bash source /home/hikos/MTranServer/migrate_ws/install/setup.bash ros2 service call /translate_en_to_zh \ mtran_ros2/srv/TranslateEnglishToChinese \ "{text: 'The robot has completed the inspection.'}" ``` Expected: `success: true`, non-empty Chinese `translation`, and empty `error`. - [ ] **Step 5: Verify offline restart** Restart the launch with `MT_OFFLINE=true` already enforced by the launch file and no network dependency. Repeat the same service request and expect the same response shape without model download attempts. - [ ] **Step 6: Inspect repository scope** Run: ```bash cd /home/hikos/MTranServer git status --short git diff --check find migrate_ws -maxdepth 4 -type f -print | sort ``` Expected: authored migration changes are only under `migrate_ws`; generated runtime, models, tools, and colcon directories are ignored. - [ ] **Step 7: Commit documentation and final corrections** ```bash git add migrate_ws/README.md migrate_ws/src/mtran_ros2 migrate_ws/.gitignore migrate_ws/models/.gitkeep git commit -m "docs: add ROS2 translation deployment guide" ``` - [ ] **Step 8: Run final verification from a clean build directory** Move the existing generated `build`, `install`, and `log` directories to a temporary directory under `/tmp`, then rerun the complete build and test commands from Step 2. Do not delete user data or model files. Expected: a clean configuration, build, and test pass.