Merge pull request #80 from gleanwork/cfreeman/server-url-normalization

Add server URL normalization for flexible .serverURL() input

Author: chris-freeman-glean

.speakeasy/gen.yaml

@@ -22,7 +22,8 @@ generation:
     allOfMergeStrategy: shallowMerge
   requestBodyFieldName: ""
   versioningStrategy: automatic
-  persistentEdits: {}
+  persistentEdits:
+    enabled: true
   tests:
     generateTests: true
     generateNewTests: false

README.md

@@ -16,16 +16,16 @@ Each namespace has its own authentication requirements and access patterns. Whil
 // Example of accessing Client namespace
 Glean glean = Glean.builder()
         .apiToken("client-token")
-        .instance("instance-name")
+        .serverURL("https://mycompany-be.glean.com")
         .build();
 glean.client().search().query()
         .searchRequest(SearchRequest.builder().query("search term").build())
         .call();
 
-// Example of accessing Indexing namespace 
+// Example of accessing Indexing namespace
 Glean glean = Glean.builder()
         .apiToken("indexing-token")
-        .instance("instance-name")
+        .serverURL("https://mycompany-be.glean.com")
         .build();
 glean.indexing().documents().index()
         .request(DocumentBulkIndexRequest.builder() /* document data */ .build())
@@ -1308,9 +1308,22 @@ many more subclasses in the JDK platform).
 <!-- Start Server Selection [server] -->
 ## Server Selection
 
-### Server Variables
+### Server URL
 
-The default server `https://{instance}-be.glean.com` contains variables and is set to `https://instance-name-be.glean.com` by default. To override default values, the following builder methods are available when initializing the SDK client instance:
+The recommended way to configure your Glean backend is using `.serverURL()` with your deployment URL:
+
+```java
+Glean sdk = Glean.builder()
+        .serverURL("https://mycompany-be.glean.com")
+        .apiToken(System.getenv().getOrDefault("GLEAN_API_TOKEN", ""))
+        .build();
+```
+
+The SDK normalizer will automatically add the `https://` scheme if omitted.
+
+### Server Variables (backwards-compatible)
+
+Alternatively, you can use `.instance()` to configure the server URL via template variable substitution. The default server `https://{instance}-be.glean.com` is set to `https://instance-name-be.glean.com` by default.
 
 | Variable   | BuilderMethod               | Default           | Description                                                                                            |
 | ---------- | --------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------ |
@@ -1333,8 +1346,7 @@ public class Application {
     public static void main(String[] args) throws Exception {
 
         Glean sdk = Glean.builder()
-                .serverIndex(0)
-                .instance("<value>")
+                .instance("instance-name")
                 .apiToken(System.getenv().getOrDefault("GLEAN_API_TOKEN", ""))
             .build();
 
@@ -1624,7 +1636,7 @@ export X_GLEAN_INCLUDE_EXPERIMENTAL="true"
 // Environment variables are automatically read by the SDK
 Glean glean = Glean.builder()
         .apiToken(System.getenv("GLEAN_API_TOKEN"))
-        .instance("instance-name")
+        .serverURL("https://mycompany-be.glean.com")
         .build();
 ```
 
@@ -1635,7 +1647,7 @@ import com.glean.api_client.glean_api_client.hooks.GleanBuilder;
 
 Glean glean = GleanBuilder.create()
         .apiToken(System.getenv("GLEAN_API_TOKEN"))
-        .instance("instance-name")
+        .serverURL("https://mycompany-be.glean.com")
         .excludeDeprecatedAfter("2026-10-15")
         .includeExperimental(true)
         .build();

src/main/java/com/glean/api_client/glean_api_client/hooks/GleanBuilder.java

@@ -20,7 +20,7 @@
  * <pre>{@code
  * Glean glean = GleanBuilder.create()
  *         .apiToken("your-api-token")
- *         .instance("instance-name")
+ *         .serverURL("https://mycompany-be.glean.com")
  *         .excludeDeprecatedAfter("2026-10-15")
  *         .includeExperimental(true)
  *         .build();

src/main/java/com/glean/api_client/glean_api_client/hooks/SDKHooks.java

@@ -13,6 +13,8 @@ private SDKHooks() {
     }
 
     public static void initialize(com.glean.api_client.glean_api_client.utils.Hooks hooks) {
+        hooks.registerSdkInit(ServerURLNormalizerHook.createSyncHook());
+
         hooks.registerAfterError(AgentFileUploadErrorHook.createSyncHook());
 
         // Register the X-Glean header hook for experimental features and deprecation testing

src/main/java/com/glean/api_client/glean_api_client/hooks/ServerURLNormalizerHook.java

@@ -0,0 +1,27 @@
+package com.glean.api_client.glean_api_client.hooks;
+
+import com.glean.api_client.glean_api_client.utils.Hook;
+
+import java.util.regex.Pattern;
+
+public final class ServerURLNormalizerHook {
+
+    private static final Pattern SCHEME_PATTERN = Pattern.compile("(?i)^https?://");
+
+    private ServerURLNormalizerHook() {
+        // prevent instantiation
+    }
+
+    static String normalize(String url) {
+        String normalized = url;
+        if (!SCHEME_PATTERN.matcher(normalized).find()) {
+            normalized = "https://" + normalized;
+        }
+        normalized = normalized.replaceAll("/+$", "");
+        return normalized;
+    }
+
+    public static Hook.SdkInit createSyncHook() {
+        return data -> new Hook.SdkInitData(normalize(data.baseUrl()), data.client());
+    }
+}

src/test/java/com/glean/api_client/glean_api_client/hooks/ServerURLNormalizerHookTest.java

@@ -0,0 +1,40 @@
+package com.glean.api_client.glean_api_client.hooks;
+
+import com.glean.api_client.glean_api_client.utils.Hook;
+
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class ServerURLNormalizerHookTest {
+
+    @ParameterizedTest
+    @CsvSource({
+        "example.glean.com,             https://example.glean.com",
+        "https://example.glean.com,     https://example.glean.com",
+        "http://localhost:8080,          http://localhost:8080",
+        "https://example.glean.com///,  https://example.glean.com",
+        "https://example.glean.com/api/v1, https://example.glean.com/api/v1",
+        "example.glean.com/,            https://example.glean.com",
+        "HTTP://EXAMPLE.COM,            HTTP://EXAMPLE.COM",
+        "HTTPS://EXAMPLE.COM,           HTTPS://EXAMPLE.COM",
+    })
+    void normalize(String input, String expected) {
+        assertEquals(expected, ServerURLNormalizerHook.normalize(input));
+    }
+
+    @ParameterizedTest
+    @CsvSource({
+        "example.glean.com,             https://example.glean.com",
+        "https://example.glean.com///,  https://example.glean.com",
+        "http://localhost:8080,          http://localhost:8080",
+    })
+    void createSyncHook(String input, String expected) {
+        Hook.SdkInit hook = ServerURLNormalizerHook.createSyncHook();
+        Hook.SdkInitData data = new Hook.SdkInitData(input, null);
+        Hook.SdkInitData result = hook.sdkInit(data);
+        assertEquals(expected, result.baseUrl());
+        assertNull(result.client());
+    }
+}