feat: add URL normalization with warning logs

- Add URL normalization support for config options
- Automatically prefix missing schemes (http://, https://)
- Log warnings when auto-correcting user-provided values
- Add comprehensive test coverage for normalization logic
- Update config files to demonstrate the feature

Changes:
- ConfigOption: Add withUrlNormalization() builder method
- ServerOptions: Apply normalization to REST, Gremlin, K8s URLs
- HugeConfig: Implement lazy cache and normalization logic
- Add ServerOptionsTest with 5 test cases
- Simplify URLs in main and Docker config

Author: bitflicker64

docker/configs/server1-conf/rest-server.properties

@@ -1,7 +1,7 @@
 # bind url
-restserver.url=http://127.0.0.1:8081
+restserver.url=127.0.0.1:8081
 # gremlin server url, need to be consistent with host and port in gremlin-server.yaml
-gremlinserver.url=http://127.0.0.1:8181
+gremlinserver.url=127.0.0.1:8181
 
 graphs=./conf/graphs
 

docker/configs/server2-conf/rest-server.properties

@@ -1,7 +1,7 @@
 # bind url
-restserver.url=http://127.0.0.1:8082
+restserver.url=127.0.0.1:8082
 # gremlin server url, need to be consistent with host and port in gremlin-server.yaml
-gremlinserver.url=http://127.0.0.1:8182
+gremlinserver.url=127.0.0.1:8182
 
 graphs=./conf/graphs
 

docker/configs/server3-conf/rest-server.properties

@@ -1,7 +1,7 @@
 # bind url
-restserver.url=http://127.0.0.1:8083
+restserver.url=127.0.0.1:8083
 # gremlin server url, need to be consistent with host and port in gremlin-server.yaml
-gremlinserver.url=http://127.0.0.1:8183
+gremlinserver.url=127.0.0.1:8183
 
 graphs=./conf/graphs
 

hugegraph-commons/hugegraph-common/src/main/java/org/apache/hugegraph/config/HugeConfig.java

@@ -43,6 +43,11 @@ public class HugeConfig extends PropertiesConfiguration {
 
     private static final Logger LOG = Log.logger(HugeConfig.class);
 
+    // Cache for url normalization metadata
+    // Populated lazily on first use to ensure OptionSpace is already registered
+    private static final Map<String, String> URL_NORMALIZATIONS = new HashMap<>();
+    private static volatile boolean cacheInitialized = false;
+
     private String configPath;
 
     public HugeConfig(Configuration config) {
@@ -232,10 +237,17 @@ private static Object normalizeUrlOptionIfNeeded(String key, Object value) {
             return value;
         }
 
-        // Normalize URL config values by adding default scheme if missing.
-        // Only applies to allowlisted URL options (see defaultSchemeFor()).
+        // Normalize URL options if configured with .withUrlNormalization()
         if (value instanceof String) {
-            return prefixSchemeIfMissing((String) value, scheme);
+            String original = (String) value;
+            String normalized = prefixSchemeIfMissing(original, scheme);
+
+            if (!original.equals(normalized)) {
+                LOG.warn("Config '{}' is missing scheme, auto-corrected to '{}'",
+                         key, normalized);
+            }
+
+            return normalized;
         }
 
         // If it ever hits here, it means config storage returned a non-string type;
@@ -244,14 +256,29 @@ private static Object normalizeUrlOptionIfNeeded(String key, Object value) {
     }
 
     private static String defaultSchemeFor(String key) {
-        TypedOption<?, ?> option = OptionSpace.get(key);
-        if (option instanceof ConfigOption) {
-            ConfigOption<?> configOption = (ConfigOption<?>) option;
-            if (configOption.needsUrlNormalization()) {
-                return configOption.getDefaultScheme();
+        ensureCacheInitialized();
+        return URL_NORMALIZATIONS.get(key);
+    }
+
+    private static void ensureCacheInitialized() {
+        if (!cacheInitialized) {
+            synchronized (URL_NORMALIZATIONS) {
+                if (!cacheInitialized) {
+                    // Populate cache from OptionSpace
+                    for (String optionKey : OptionSpace.keys()) {
+                        TypedOption<?, ?> option = OptionSpace.get(optionKey);
+                        if (option instanceof ConfigOption) {
+                            ConfigOption<?> configOption = (ConfigOption<?>) option;
+                            if (configOption.needsUrlNormalization()) {
+                                URL_NORMALIZATIONS.put(optionKey,
+                                                       configOption.getDefaultScheme());
+                            }
+                        }
+                    }
+                    cacheInitialized = true;
+                }
             }
         }
-        return null;
     }
 
     private static String prefixSchemeIfMissing(String raw, String scheme) {
@@ -263,11 +290,18 @@ private static String prefixSchemeIfMissing(String raw, String scheme) {
             return s;
         }
 
-        // Keep original string if scheme already exists
-        String lower = s.toLowerCase();
-        if (lower.startsWith("http://") || lower.startsWith("https://")) {
-            return lower;  // Return LOWERCASE version
+        int scIdx = s.indexOf("://");
+        if (scIdx > 0) {
+            // Normalize existing scheme to lowercase while preserving the rest
+            String existingScheme = s.substring(0, scIdx).toLowerCase();
+            String rest = s.substring(scIdx + 3); // skip the "://" delimiter
+            return existingScheme + "://" + rest;
+        }
+
+        String defaultScheme = scheme == null ? "" : scheme;
+        if (!defaultScheme.isEmpty() && !defaultScheme.endsWith("://")) {
+            defaultScheme = defaultScheme + "://";
         }
-        return scheme + lower;  // Return scheme + LOWERCASE input
+        return defaultScheme + s;
     }
 }

hugegraph-server/hugegraph-dist/src/assembly/static/conf/rest-server.properties

@@ -1,9 +1,9 @@
 # bind url
 # could use '0.0.0.0' or specified (real)IP to expose external network access
-restserver.url=http://127.0.0.1:8080
+restserver.url=127.0.0.1:8080
 #restserver.enable_graphspaces_filter=false
 # gremlin server url, need to be consistent with host and port in gremlin-server.yaml
-#gremlinserver.url=http://127.0.0.1:8182
+#gremlinserver.url=127.0.0.1:8182
 
 graphs=./conf/graphs
 

hugegraph-server/hugegraph-test/src/test/java/org/apache/hugegraph/unit/config/ServerOptionsTest.java

@@ -55,22 +55,68 @@ public void testUrlOptionNormalizeAddsDefaultScheme() {
 
     @Test
     public void testUrlNormalizationEdgeCases() {
+        // Whitespace trimming
         PropertiesConfiguration conf = new PropertiesConfiguration();
         conf.setProperty("restserver.url", "  127.0.0.1:8080  ");
         HugeConfig config = new HugeConfig(conf);
         Assert.assertEquals("http://127.0.0.1:8080",
                             config.get(ServerOptions.REST_SERVER_URL));
 
+        // Case normalization
         conf = new PropertiesConfiguration();
         conf.setProperty("restserver.url", "HTTP://127.0.0.1:8080");
         config = new HugeConfig(conf);
         Assert.assertEquals("http://127.0.0.1:8080",
                             config.get(ServerOptions.REST_SERVER_URL));
 
+        // IPv6 without scheme
         conf = new PropertiesConfiguration();
         conf.setProperty("restserver.url", "[::1]:8080");
         config = new HugeConfig(conf);
         Assert.assertEquals("http://[::1]:8080",
                             config.get(ServerOptions.REST_SERVER_URL));
+
+        // IPv6 with existing scheme
+        conf = new PropertiesConfiguration();
+        conf.setProperty("restserver.url", "http://[::1]:8080");
+        config = new HugeConfig(conf);
+        Assert.assertEquals("http://[::1]:8080",
+                            config.get(ServerOptions.REST_SERVER_URL));
+    }
+
+    @Test
+    public void testUrlNormalizationPreservesHostnameCase() {
+        // Uppercase scheme + mixed-case hostname
+        PropertiesConfiguration conf = new PropertiesConfiguration();
+        conf.setProperty("restserver.url", "HTTP://MyServer:8080");
+        HugeConfig config = new HugeConfig(conf);
+        // Should lowercase ONLY the scheme, preserve "MyServer"
+        Assert.assertEquals("http://MyServer:8080",
+                            config.get(ServerOptions.REST_SERVER_URL));
+
+        // Use server.k8s_url for HTTPS test (it defaults to https://)
+        conf = new PropertiesConfiguration();
+        conf.setProperty("server.k8s_url", "HTTPS://MyHost:8888");
+        config = new HugeConfig(conf);
+        Assert.assertEquals("https://MyHost:8888",
+                            config.get(ServerOptions.SERVER_K8S_URL));
+    }
+
+    @Test
+    public void testUrlNormalizationPreservesPathCase() {
+        PropertiesConfiguration conf = new PropertiesConfiguration();
+        conf.setProperty("restserver.url", "http://127.0.0.1:8080/SomePath/CaseSensitive");
+        HugeConfig config = new HugeConfig(conf);
+        Assert.assertEquals("http://127.0.0.1:8080/SomePath/CaseSensitive",
+                            config.get(ServerOptions.REST_SERVER_URL));
+    }
+
+    @Test
+    public void testHttpsSchemeIsNotDowngraded() {
+        PropertiesConfiguration conf = new PropertiesConfiguration();
+        conf.setProperty("restserver.url", "https://127.0.0.1:8080");
+        HugeConfig config = new HugeConfig(conf);
+        Assert.assertEquals("https://127.0.0.1:8080",
+                            config.get(ServerOptions.REST_SERVER_URL));
     }
 }