fix(toplingdb): align explicit provider configuration

Author: WaterWhisperer

.specs/hugegraph-server/ToplingDB/design.md

@@ -40,34 +40,39 @@ sequenceDiagram
 
 ### RocksDB Startup Logic
 
-Use reflection to detect whether ToplingDB APIs are available. If present, attempt to start the storage engine using ToplingDB; otherwise, fall back to standard RocksDB APIs.
+HugeGraph routes the main RocksDB open/close paths through `RocksDBProviderLoader`.
+Providers are discovered via Java SPI, but the active provider is selected explicitly by
+`rocksdb.provider`. `standard` uses vanilla RocksDB; `topling` requires
+`org.rocksdb.SidePluginRepo` to be available at runtime.
 
 ```mermaid
 sequenceDiagram
   autonumber
-  participant Store as HugeGraph Store
+  participant Store as HugeGraph Server/PD/Store
   participant Config as HugeConfig
-  participant Sessions as RocksDBStdSessions
-  participant SPR as SidePluginRepo (Reflection)
+  participant Loader as RocksDBProviderLoader
+  participant Provider as Configured Provider
   participant Repo as Repo Instance
   participant Rocks as RocksDB
 
-  Store->>Config: Read OPTION_PATH / OPEN_HTTP
-  Store->>Sessions: Create Sessions(..., optionPath, openHttp)
-  alt optionPath provided and SPR available
-    Sessions->>SPR: Reflectively load/create Repo
-    Sessions->>Repo: importAutoFile(optionPath)
-    Sessions->>Repo: open (with JSON descriptor)
-    opt openHttp is true and instance is GRAPH_STORE
-      Sessions->>Repo: startHttpServer()
+  Store->>Config: Read PROVIDER / OPTION_PATH / OPEN_HTTP
+  Store->>Loader: selectProviderIfNeeded(provider)
+  Store->>Loader: openRocksDB(..., optionPath, openHttp)
+  Loader->>Provider: openRocksDB(...)
+  alt provider is standard
+    Provider->>Rocks: RocksDB.open(...)
+  else provider is topling and optionPath valid
+    Provider->>Repo: Reflectively create SidePluginRepo
+    Provider->>Repo: importAutoFile(optionPath)
+    Provider->>Repo: openDB(JSON descriptor)
+    opt Server openHttp is true and instance is GRAPH_STORE
+      Provider->>Repo: startHttpServer()
     end
-    Sessions->>Rocks: Get RocksDB instance (with CF handles)
-    Sessions-->>Store: Return OpenedRocksDB(repo, handles)
-  else optionPath not provided or SPR unavailable
-    Sessions->>Rocks: Standard open()
-    Sessions-->>Store: Return OpenedRocksDB(null, handles)
+  else provider is topling but optionPath pre-validation fails
+    Provider->>Rocks: RocksDB.open(...)
   end
-  note over Store,Sessions: On shutdown, if repo exists, call repo.closeAllDB()
+  Loader-->>Store: Return RocksDB instance
+  note over Store,Loader: On shutdown, close through the active provider; Topling closes Repo when present.
 ```
 
 ## Involved Modules
@@ -168,19 +173,30 @@ Both `init-hugegraph.sh` and `start-hugegraph.sh` now invoke `preload-topling.sh
 
 ### HugeGraph Configuration Options for RocksDB
 
-Two new configuration options were added to `hugegraph.properties`: `option_path` for the YAML file and `open_http` to enable the Web Server.
+Three RocksDB provider options were added: `provider` selects standard RocksDB or ToplingDB,
+`option_path` points to the YAML file, and `open_http` enables the Web Server.
 
 ```properties
 # rocksdb backend config
 #rocksdb.data_path=/path/to/disk
 #rocksdb.wal_path=/path/to/disk
-#rocksdb.option_path=./conf/graphs/rocksdb_plus.yaml
+#rocksdb.provider=topling
+#rocksdb.option_path=./conf/graphs/rocksdb_server.yaml
 #rocksdb.open_http=true
 ```
 
 Java-side parsing and default values:
 
 ```java
+public static final ConfigOption<String> PROVIDER =
+        new ConfigOption<>(
+                "rocksdb.provider",
+                "The RocksDB engine provider. 'standard' for vanilla RocksDB, "
+                + "'topling' for ToplingDB (requires addon installation).",
+                allowValues("standard", "topling"),
+                "standard"
+        );
+
 public static final ConfigOption<String> OPTION_PATH =
         new ConfigOption<>(
                 "rocksdb.option_path",
@@ -200,29 +216,30 @@ public static final ConfigOption<Boolean> OPEN_HTTP =
 
 ### ToplingDB Startup Logic
 
-When `option_path` is configured and the JAR contains ToplingDB APIs, HugeGraph will load the YAML file and start ToplingDB. Otherwise, it falls back to standard RocksDB.
+When `rocksdb.provider=topling`, `option_path` is configured, pre-validation passes, and the JAR
+contains ToplingDB APIs, HugeGraph will load the YAML file and start ToplingDB. If
+`rocksdb.provider=standard`, HugeGraph uses standard RocksDB.
 
-To keep port configuration simple, the Web Server is only enabled for the `GRAPH_STORE` instance.
+For HugeGraph Server, the Web Server is only enabled for the `GRAPH_STORE` instance. PD and
+Store pass their component-level HTTP flag to the provider.
 
 ```mermaid
 flowchart LR
-    A[Start Initialization] --> B{Is optionPath provided?}
-
-    B -- No --> Z[Use standard RocksDB to open DB] --> O[Finish standard init]
-
-    B -- Yes --> C{Is SidePluginRepo class available?}
-    C -- No --> Z
+    A[Start Initialization] --> P{rocksdb.provider}
+    P -- standard --> Z[Use StandardRocksDBProvider] --> O[Finish standard init]
+    P -- topling --> S{Is SidePluginRepo available?}
+    S -- No --> F[Fail startup]
+    S -- Yes --> B{Is optionPath provided and valid?}
 
-    C -- Yes --> D[Set useTopling = true] --> E["Load SidePluginRepo class and call importAutoFile(optionPath)"]
+    B -- No --> Z
+    B -- Yes --> E["ToplingRocksDBProvider calls importAutoFile(optionPath)"]
 
-    E --> K{Is openHttp true?}
+    E --> K{Should this component start HTTP?}
     K -- No --> M[Finish Topling init]
-    K -- Yes --> L{Is dbName GRAPH_STORE?}
-    L -- No --> M
-    L -- Yes --> N["startHttpServer()"] --> M
+    K -- Yes --> N["startHttpServer()"] --> M
 ```
 
 ## Design Decisions and Rationale
 
-1. **Why is the Web Server only started for GRAPH_STORE?**
+1. **Why does HugeGraph Server only start the Web Server for GRAPH_STORE?**
     - All graph data is stored in GRAPH_STORE, and performance tuning and observability are primarily focused on this instance.

.specs/hugegraph-server/ToplingDB/task.md

@@ -12,7 +12,7 @@ When using an IDE such as IntelliJ IDEA, you need to configure the following env
 
 ```shell
 LD_LIBRARY_PATH=/path/to/your/library:$LD_LIBRARY_PATH
-LD_PRELOAD=libjemalloc.so:librocksdbjni-linux64.so
+LD_PRELOAD=/path/to/libjemalloc.so:/path/to/your/library/librocksdbjni-linux64.so
 ```
 
 When running from the terminal, simply use `init-store.sh` and `start-hugegraph.sh`, as `preload-topling.sh` is already embedded in these scripts.
@@ -25,9 +25,10 @@ When running from the terminal, simply use `init-store.sh` and `start-hugegraph.
 
 ## 2. Compatibility with ToplingDB and Standard RocksDB
 
-- [x] **2.1 Modify openRocksDB logic in RocksDBStdSession**
-  - Use reflection to detect whether the current JAR contains ToplingDB APIs; if so, start the storage engine using ToplingDB
-  - If not available, fall back to the standard RocksDB API for engine startup
+- [x] **2.1 Add a RocksDB provider SPI and route main open/close paths through it**
+  - Use `RocksDBProviderLoader` to discover standard RocksDB and ToplingDB providers
+  - Select the active provider explicitly with `rocksdb.provider`
+  - Use reflection in `ToplingRocksDBProvider` to detect whether the current JAR contains `org.rocksdb.SidePluginRepo`
 
 ## 3. Add Configuration Options for ToplingDB in HugeGraph
 
@@ -40,7 +41,12 @@ When running from the terminal, simply use `init-store.sh` and `start-hugegraph.
   - Type: boolean, used to specify whether to enable the ToplingDB Web Server
   - Allow users to configure Web Server activation via `rocksdb.open_http` in `hugegraph.properties`
   - The Web Server port is defined in the YAML file specified by `option_path`, under `http.listening_ports`
-  - For simplicity, the Web Server is only enabled for the `GRAPH_STORE` instance that stores graph data
+  - For HugeGraph Server, the Web Server is only enabled for the `GRAPH_STORE` instance that stores graph data
+
+- [x] **3.3 Add `rocksdb.provider` configuration**
+  - Type: string, valid values: `standard` and `topling`
+  - Default: `standard`
+  - Prevent ToplingDB from being enabled implicitly just because a ToplingDB-capable JAR is on the classpath
 
 ## 4. End-to-End Performance Testing
 

docs/toplingdb/toplingdb-troubleshooting.md

@@ -2,13 +2,13 @@
 
 ## Issues
 
-### Issue 1: Startup Failure Due to YAML Format Error
+### Issue 1: YAML Configuration Error
 
 Sample log output:
 
 ```java
-2025-10-15 01:55:50 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStdSessions - SidePluginRepo found. Will attempt to open multi CFs RocksDB using Topling plugin.
-21:1: (891B):ERROR: 
+2025-10-15 01:55:50 [db-open-1] [INFO] o.a.h.r.p.ToplingRocksDBProvider - SidePluginRepo found. Will attempt to open default CF RocksDB using Topling.
+21:1: (891B):ERROR:
 sideplugin/rockside/3rdparty/rapidyaml/src/c4/yml/parse.cpp:3310: ERROR parsing yml: parse error: incorrect indentation?
 ```
 
@@ -18,19 +18,49 @@ sideplugin/rockside/3rdparty/rapidyaml/src/c4/yml/parse.cpp:3310: ERROR parsing
 2. Validate YAML syntax:
 
    ```bash
-   python -c "import yaml; yaml.safe_load(open('conf/graphs/rocksdb_plus.yaml'))"
+   python -c "import yaml; yaml.safe_load(open('conf/graphs/rocksdb_server.yaml'))"
    ```
 
 3. Review the specific error message in the logs for further clues.
 
+HugeGraph performs basic path and YAML validation before enabling ToplingDB. If this
+pre-validation fails, HugeGraph falls back to standard RocksDB behavior inside the ToplingDB
+provider. If the file passes basic YAML validation but `SidePluginRepo.importAutoFile()` or
+`openDB()` fails, startup fails with the corresponding ToplingDB error and the YAML file should
+be fixed.
+
 ---
 
-### Issue 2: Web Server Port Conflict
+### Issue 2: ToplingDB Provider Not Available
+
+When `rocksdb.provider=topling` is configured but the runtime `rocksdbjni` JAR does not contain
+`org.rocksdb.SidePluginRepo`, HugeGraph fails provider activation instead of silently switching
+to the standard provider.
+
+**Solution**:
+
+1. If you want standard RocksDB, set:
+
+   ```properties
+   rocksdb.provider=standard
+   ```
+
+2. If you want ToplingDB, confirm that Maven or the deployment addon provides a ToplingDB-capable
+   `rocksdbjni` artifact.
+3. Inspect the runtime JAR:
+
+   ```bash
+   jar tf lib/rocksdbjni-*.jar | grep org/rocksdb/SidePluginRepo.class
+   ```
+
+---
+
+### Issue 3: Web Server Port Conflict
 
 Sample log output:
 
 ```java
-2025-10-15 01:57:34 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStdSessions - SidePluginRepo found. Will attempt to open multi CFs RocksDB using Topling plugin.
+2025-10-15 01:57:34 [db-open-1] [INFO] o.a.h.r.p.ToplingRocksDBProvider - SidePluginRepo found. Will attempt to open default CF RocksDB using Topling.
 2025-10-15 01:57:34 [db-open-1] [ERROR] o.a.h.b.s.r.RocksDBStore - Failed to open RocksDB 'rocksdb-data/data/g'
 org.rocksdb.RocksDBException: rocksdb::Status rocksdb::SidePluginRepo::StartHttpServer(): null context when constructing CivetServer. Possible problem binding to port.
     at org.rocksdb.SidePluginRepo.startHttpServer(Native Method) ~[rocksdbjni-8.10.2-20250804.074027-4.jar:?]
@@ -49,7 +79,7 @@ org.rocksdb.RocksDBException: rocksdb::Status rocksdb::SidePluginRepo::StartHttp
 
 ---
 
-### Issue 3: Database Initialization Failure
+### Issue 4: Database Initialization Failure
 
 This error indicates the database lock file cannot be acquired, possibly due to insufficient write permissions or another process holding the lock:
 
@@ -64,7 +94,8 @@ Caused by: org.rocksdb.RocksDBException: While lock file: rocksdb-data/data/m/LO
 1. Confirm the configuration file path is correct:
 
    ```properties
-   rocksdb.option_path=./conf/graphs/rocksdb_plus.yaml
+   rocksdb.provider=topling
+   rocksdb.option_path=./conf/graphs/rocksdb_server.yaml
    ```
 
 2. Check permissions on the data directory to ensure the running user has read/write access.
@@ -76,6 +107,23 @@ Caused by: org.rocksdb.RocksDBException: While lock file: rocksdb-data/data/m/LO
 
 ---
 
+### Issue 5: Ubuntu 24.04+ libaio Compatibility
+
+Some ToplingDB native libraries may expect the legacy `libaio.so.1` name, while Ubuntu 24.04+
+ships the time64 library as `libaio.so.1t64`. The preload script currently creates a
+compatibility symlink when running on Ubuntu 24.04+ and `libaio.so.1` is missing.
+
+If startup fails with a missing `libaio.so.1` error, install the system package first:
+
+```bash
+sudo apt-get install libaio1t64
+```
+
+Then retry startup. If your environment does not allow scripts to use `sudo`, create the
+compatibility symlink manually or ask the system administrator to provide it.
+
+---
+
 ## Log Analysis
 
 ### Enable Debug Logging