SCANJLIB-263 Add support for the upcoming SonarQube Cloud US region

Author: henryju

lib/src/main/java/org/sonarsource/scanner/lib/EnvironmentConfig.java

@@ -41,6 +41,7 @@ public class EnvironmentConfig {
   private static final String SONAR_HOST_URL_ENV_VAR = "SONAR_HOST_URL";
   private static final String SONAR_USER_HOME_ENV_VAR = "SONAR_USER_HOME";
   public static final String TOKEN_ENV_VARIABLE = "SONAR_TOKEN";
+  public static final String REGION_ENV_VARIABLE = "SONAR_REGION";
 
   private EnvironmentConfig() {
     // only static methods
@@ -54,7 +55,8 @@ public static Map<String, String> load(Map<String, String> env) {
     var loadedProps = new HashMap<String, String>();
     Optional.ofNullable(env.get(SONAR_HOST_URL_ENV_VAR)).ifPresent(url -> loadedProps.put(ScannerProperties.HOST_URL, url));
     Optional.ofNullable(env.get(SONAR_USER_HOME_ENV_VAR)).ifPresent(path -> loadedProps.put(ScannerProperties.SONAR_USER_HOME, path));
-    Optional.ofNullable(env.get(TOKEN_ENV_VARIABLE)).ifPresent(path -> loadedProps.put(ScannerProperties.SONAR_TOKEN, path));
+    Optional.ofNullable(env.get(TOKEN_ENV_VARIABLE)).ifPresent(token -> loadedProps.put(ScannerProperties.SONAR_TOKEN, token));
+    Optional.ofNullable(env.get(REGION_ENV_VARIABLE)).ifPresent(region -> loadedProps.put(ScannerProperties.SONAR_REGION, region));
     env.forEach((key, value) -> {
       if (!key.equals(SONAR_SCANNER_JSON_PARAMS) && key.startsWith(GENERIC_ENV_PREFIX)) {
         processEnvVariable(key, value, loadedProps);

lib/src/main/java/org/sonarsource/scanner/lib/ScannerEngineBootstrapper.java

@@ -37,6 +37,8 @@
 import org.sonarsource.scanner.lib.internal.MessageException;
 import org.sonarsource.scanner.lib.internal.SuccessfulBootstrap;
 import org.sonarsource.scanner.lib.internal.cache.FileCache;
+import org.sonarsource.scanner.lib.internal.endpoint.ScannerEndpoint;
+import org.sonarsource.scanner.lib.internal.endpoint.ScannerEndpointResolver;
 import org.sonarsource.scanner.lib.internal.facade.forked.NewScannerEngineFacade;
 import org.sonarsource.scanner.lib.internal.facade.forked.ScannerEngineLauncherFactory;
 import org.sonarsource.scanner.lib.internal.facade.inprocess.InProcessScannerEngineFacade;
@@ -77,8 +79,7 @@ public class ScannerEngineBootstrapper {
 
   private static final Logger LOG = LoggerFactory.getLogger(ScannerEngineBootstrapper.class);
 
-  private static final String SONARCLOUD_HOST = "https://sonarcloud.io";
-  private static final String SONARCLOUD_REST_API = "https://api.sonarcloud.io";
+
   static final String SQ_VERSION_NEW_BOOTSTRAPPING = "10.6";
   static final String SQ_VERSION_TOKEN_AUTHENTICATION = "10.0";
 
@@ -125,37 +126,38 @@ public ScannerEngineBootstrapResult bootstrap() {
     if (LOG.isDebugEnabled()) {
       LOG.debug("Scanner max available memory: {}", FileUtils.byteCountToDisplaySize(Runtime.getRuntime().maxMemory()));
     }
-    initBootstrapDefaultValues();
+    var endpoint = ScannerEndpointResolver.resolveEndpoint(bootstrapProperties);
+    initBootstrapDefaultValues(endpoint);
     var immutableProperties = Map.copyOf(bootstrapProperties);
     var sonarUserHome = resolveSonarUserHome(immutableProperties);
     var httpConfig = new HttpConfig(immutableProperties, sonarUserHome, system);
-    var isSonarCloud = isSonarCloud(immutableProperties);
+    var isSonarQubeCloud = endpoint.isSonarQubeCloud();
     var isSimulation = immutableProperties.containsKey(InternalProperties.SCANNER_DUMP_TO_FILE);
     var fileCache = FileCache.create(sonarUserHome);
 
     if (isSimulation) {
       var serverVersion = immutableProperties.getOrDefault(InternalProperties.SCANNER_VERSION_SIMULATION, "9.9");
-      return new SuccessfulBootstrap(new SimulationScannerEngineFacade(immutableProperties, isSonarCloud, serverVersion));
+      return new SuccessfulBootstrap(new SimulationScannerEngineFacade(immutableProperties, isSonarQubeCloud, serverVersion));
     }
 
     // No HTTP call should be made before this point
     try {
       scannerHttpClient.init(httpConfig);
 
-      var serverVersion = !isSonarCloud ? getServerVersion(scannerHttpClient) : null;
+      var serverVersion = !isSonarQubeCloud ? getServerVersion(scannerHttpClient) : null;
 
-      if (!isSonarCloud && VersionUtils.isAtLeastIgnoringQualifier(serverVersion, SQ_VERSION_TOKEN_AUTHENTICATION) && Objects.nonNull(httpConfig.getLogin())) {
+      if (!isSonarQubeCloud && VersionUtils.isAtLeastIgnoringQualifier(serverVersion, SQ_VERSION_TOKEN_AUTHENTICATION) && Objects.nonNull(httpConfig.getLogin())) {
         LOG.warn("Use of '{}' property has been deprecated in favor of '{}' (or the env variable alternative '{}'). Please use the latter when passing a token.", SONAR_LOGIN,
           SONAR_TOKEN, TOKEN_ENV_VARIABLE);
       }
 
       ScannerEngineFacade scannerFacade;
-      if (isSonarCloud || VersionUtils.isAtLeastIgnoringQualifier(serverVersion, SQ_VERSION_NEW_BOOTSTRAPPING)) {
+      if (isSonarQubeCloud || VersionUtils.isAtLeastIgnoringQualifier(serverVersion, SQ_VERSION_NEW_BOOTSTRAPPING)) {
         var launcher = scannerEngineLauncherFactory.createLauncher(scannerHttpClient, fileCache, immutableProperties);
 
         var adaptedProperties = adaptSslPropertiesToScannerProperties(immutableProperties, httpConfig);
 
-        scannerFacade = new NewScannerEngineFacade(adaptedProperties, launcher, isSonarCloud, serverVersion);
+        scannerFacade = new NewScannerEngineFacade(adaptedProperties, launcher, isSonarQubeCloud, serverVersion);
       } else {
         var launcher = launcherFactory.createLauncher(scannerHttpClient, fileCache);
         var adaptedProperties = adaptDeprecatedPropertiesForInProcessBootstrapping(immutableProperties, httpConfig);
@@ -201,7 +203,7 @@ private static void logWithStacktraceOnlyIfDebug(String message, Throwable t) {
   }
 
   private static void logServerType(ScannerEngineFacade engine) {
-    if (engine.isSonarCloud()) {
+    if (engine.isSonarQubeCloud()) {
       LOG.info("Communicating with SonarQube Cloud");
     } else {
       LOG.info("Communicating with {} {}", engine.getServerLabel(), engine.getServerVersion());
@@ -295,10 +297,9 @@ private static String formatMessage(Exception e) {
     return e.getMessage();
   }
 
-  private void initBootstrapDefaultValues() {
-    setBootstrapPropertyIfNotAlreadySet(ScannerProperties.HOST_URL, getSonarCloudUrl());
-    setBootstrapPropertyIfNotAlreadySet(ScannerProperties.API_BASE_URL,
-      isSonarCloud(bootstrapProperties) ? SONARCLOUD_REST_API : (StringUtils.removeEnd(bootstrapProperties.get(ScannerProperties.HOST_URL), "/") + "/api/v2"));
+  private void initBootstrapDefaultValues(ScannerEndpoint endpoint) {
+    setBootstrapPropertyIfNotAlreadySet(ScannerProperties.HOST_URL, endpoint.getWebEndpoint());
+    setBootstrapPropertyIfNotAlreadySet(ScannerProperties.API_BASE_URL, endpoint.getApiEndpoint());
     if (!bootstrapProperties.containsKey(SCANNER_OS)) {
       setBootstrapProperty(SCANNER_OS, new OsResolver(system, new Paths2()).getOs().name().toLowerCase(Locale.ENGLISH));
     }
@@ -328,14 +329,6 @@ static Map<String, String> adaptSslPropertiesToScannerProperties(Map<String, Str
     return Map.copyOf(result);
   }
 
-  private String getSonarCloudUrl() {
-    return bootstrapProperties.getOrDefault(ScannerProperties.SONARCLOUD_URL, SONARCLOUD_HOST);
-  }
-
-  private boolean isSonarCloud(Map<String, String> properties) {
-    return getSonarCloudUrl().equals(properties.get(ScannerProperties.HOST_URL));
-  }
-
   private void setBootstrapPropertyIfNotAlreadySet(String key, @Nullable String value) {
     if (!bootstrapProperties.containsKey(key) && value != null) {
       setBootstrapProperty(key, value);

lib/src/main/java/org/sonarsource/scanner/lib/ScannerEngineFacade.java

@@ -39,7 +39,7 @@ public interface ScannerEngineFacade extends AutoCloseable {
   /**
    * @return true if the scanner is connected to SonarQube Cloud, false otherwise
    */
-  boolean isSonarCloud();
+  boolean isSonarQubeCloud();
 
 
   /**

lib/src/main/java/org/sonarsource/scanner/lib/ScannerProperties.java

@@ -33,7 +33,7 @@ private ScannerProperties() {
   }
 
   /**
-   * URL of the Sonar server, default to SonarCloud
+   * URL of the SonarQube Server, default to SonarQube Cloud if not set
    */
   public static final String HOST_URL = "sonar.host.url";
 
@@ -43,9 +43,14 @@ private ScannerProperties() {
   public static final String API_BASE_URL = "sonar.scanner.apiBaseUrl";
 
   /**
-   * URL of the SonarCloud server, default to https://sonarcloud.io. Useful for testing purposes.
+   * URL of the SonarQube Cloud instance, default to https://sonarcloud.io. Useful for testing purposes.
    */
-  public static final String SONARCLOUD_URL = "sonar.scanner.sonarcloudUrl";
+  public static final String SONARQUBE_CLOUD_URL = "sonar.scanner.sonarcloudUrl";
+
+  /**
+   * SonarQube Cloud region.
+   */
+  public static final String SONAR_REGION = "sonar.region";
 
   /**
    * Working directory containing generated reports and temporary data.

lib/src/main/java/org/sonarsource/scanner/lib/internal/endpoint/OfficialSonarQubeCloudInstance.java

@@ -0,0 +1,65 @@
+/*
+ * SonarScanner Java Library
+ * Copyright (C) 2011-2025 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonarsource.scanner.lib.internal.endpoint;
+
+import java.util.Arrays;
+import java.util.Locale;
+import java.util.Optional;
+import java.util.Set;
+import java.util.stream.Collectors;
+import javax.annotation.Nullable;
+import org.apache.commons.lang3.StringUtils;
+
+public enum OfficialSonarQubeCloudInstance {
+  GLOBAL("https://sonarcloud.io", "https://api.sonarcloud.io"),
+  US("https://sonarqube.us", "https://api.sonarqube.us");
+
+
+  private final ScannerEndpoint endpoint;
+
+  OfficialSonarQubeCloudInstance(String webEndpoint, String apiEndpoint) {
+    this.endpoint = new ScannerEndpoint(webEndpoint, apiEndpoint, true);
+  }
+
+  public static Set<String> getRegionCodes() {
+    return Arrays.stream(OfficialSonarQubeCloudInstance.values()).filter(r -> r != GLOBAL).map(Enum::name).map(s -> s.toLowerCase(Locale.ENGLISH)).collect(Collectors.toSet());
+  }
+
+  public static Optional<OfficialSonarQubeCloudInstance> fromRegionCode(@Nullable String regionCode) {
+    if (StringUtils.isBlank(regionCode)) {
+      return Optional.of(GLOBAL);
+    }
+    try {
+      return Optional.of(OfficialSonarQubeCloudInstance.valueOf(regionCode.toUpperCase(Locale.ENGLISH)));
+    } catch (IllegalArgumentException e) {
+      return Optional.empty();
+    }
+  }
+
+  public static Optional<OfficialSonarQubeCloudInstance> fromWebEndpoint(String url) {
+    return Arrays.stream(OfficialSonarQubeCloudInstance.values())
+      .filter(r -> r.endpoint.getWebEndpoint().equals(url))
+      .findFirst();
+  }
+
+  public ScannerEndpoint getEndpoint() {
+    return endpoint;
+  }
+}

lib/src/main/java/org/sonarsource/scanner/lib/internal/endpoint/ScannerEndpoint.java

@@ -0,0 +1,45 @@
+/*
+ * SonarScanner Java Library
+ * Copyright (C) 2011-2025 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonarsource.scanner.lib.internal.endpoint;
+
+public class ScannerEndpoint {
+
+  private final String webEndpoint;
+  private final String apiEndpoint;
+  private final boolean isSonarQubeCloud;
+
+  public ScannerEndpoint(String webEndpoint, String apiEndpoint, boolean isSonarQubeCloud) {
+    this.webEndpoint = webEndpoint;
+    this.apiEndpoint = apiEndpoint;
+    this.isSonarQubeCloud = isSonarQubeCloud;
+  }
+
+  public boolean isSonarQubeCloud() {
+    return isSonarQubeCloud;
+  }
+
+  public String getApiEndpoint() {
+    return apiEndpoint;
+  }
+
+  public String getWebEndpoint() {
+    return webEndpoint;
+  }
+}

lib/src/main/java/org/sonarsource/scanner/lib/internal/endpoint/ScannerEndpointResolver.java

@@ -0,0 +1,104 @@
+/*
+ * SonarScanner Java Library
+ * Copyright (C) 2011-2025 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonarsource.scanner.lib.internal.endpoint;
+
+import java.util.Map;
+import java.util.Optional;
+import org.apache.commons.lang3.StringUtils;
+import org.sonarsource.scanner.lib.EnvironmentConfig;
+import org.sonarsource.scanner.lib.ScannerProperties;
+import org.sonarsource.scanner.lib.internal.MessageException;
+
+import static java.lang.String.format;
+import static java.util.stream.Collectors.toList;
+
+public class ScannerEndpointResolver {
+
+  private ScannerEndpointResolver() {
+  }
+
+  public static ScannerEndpoint resolveEndpoint(Map<String, String> properties) {
+    if (properties.containsKey(ScannerProperties.HOST_URL)) {
+      return resolveEndpointFromSonarHostUrl(properties);
+    }
+    return resolveSonarQubeCloudEndpoint(properties);
+  }
+
+  private static ScannerEndpoint resolveSonarQubeCloudEndpoint(Map<String, String> properties) {
+    var hasCloudUrl = properties.containsKey(ScannerProperties.SONARQUBE_CLOUD_URL);
+    if (hasCloudUrl) {
+      return resolveCustomSonarQubeCloudEndpoint(properties);
+    }
+    failIfApiEndpointAloneDefined(properties);
+    var regionCode = properties.get(ScannerProperties.SONAR_REGION);
+    return OfficialSonarQubeCloudInstance.fromRegionCode(regionCode)
+      .orElseThrow(() -> new MessageException(
+        format("Invalid region '%s'. Valid regions are: %s. Please check the '%s' property or the '%s' environment variable.",
+          regionCode, StringUtils.join(OfficialSonarQubeCloudInstance.getRegionCodes().stream().map(r -> "'" + r + "'").collect(toList()), ", "),
+          ScannerProperties.SONAR_REGION, EnvironmentConfig.REGION_ENV_VARIABLE)))
+      .getEndpoint();
+  }
+
+  private static void failIfApiEndpointAloneDefined(Map<String, String> properties) {
+    var hasApiUrl = properties.containsKey(ScannerProperties.API_BASE_URL);
+    if (hasApiUrl) {
+      throw new MessageException(format("Defining '%s' without '%s' is not supported.", ScannerProperties.API_BASE_URL, ScannerProperties.SONARQUBE_CLOUD_URL));
+    }
+  }
+
+  private static ScannerEndpoint resolveCustomSonarQubeCloudEndpoint(Map<String, String> properties) {
+    var hasApiUrl = properties.containsKey(ScannerProperties.API_BASE_URL);
+    var maybeCloudInstance = maybeResolveOfficialSonarQubeCloud(properties, ScannerProperties.SONARQUBE_CLOUD_URL);
+    if (maybeCloudInstance.isPresent()) {
+      return maybeCloudInstance.get();
+    }
+    if (!hasApiUrl) {
+      throw new MessageException(format("Defining a custom '%s' without providing '%s' is not supported.", ScannerProperties.SONARQUBE_CLOUD_URL, ScannerProperties.API_BASE_URL));
+    }
+    return new ScannerEndpoint(
+      properties.get(ScannerProperties.SONARQUBE_CLOUD_URL),
+      properties.get(ScannerProperties.API_BASE_URL), true);
+  }
+
+  private static MessageException inconsistentUrlAndRegion(String prop2) {
+    return new MessageException(format("Inconsistent values for properties '%s' and '%s'. Please only specify one of the two properties.", ScannerProperties.SONAR_REGION, prop2));
+  }
+
+  private static ScannerEndpoint resolveEndpointFromSonarHostUrl(Map<String, String> properties) {
+    return maybeResolveOfficialSonarQubeCloud(properties, ScannerProperties.HOST_URL)
+      .orElse(new SonarQubeServer(properties.get(ScannerProperties.HOST_URL)));
+  }
+
+  private static Optional<ScannerEndpoint> maybeResolveOfficialSonarQubeCloud(Map<String, String> properties, String urlPropName) {
+    var maybeCloudInstance = OfficialSonarQubeCloudInstance.fromWebEndpoint(properties.get(urlPropName));
+    var hasRegion = properties.containsKey(ScannerProperties.SONAR_REGION);
+    if (maybeCloudInstance.isPresent()) {
+      if (hasRegion && OfficialSonarQubeCloudInstance.fromRegionCode(properties.get(ScannerProperties.SONAR_REGION)).filter(maybeCloudInstance.get()::equals).isEmpty()) {
+        throw inconsistentUrlAndRegion(urlPropName);
+      }
+      return Optional.of(maybeCloudInstance.get().getEndpoint());
+    }
+    if (hasRegion) {
+      throw inconsistentUrlAndRegion(urlPropName);
+    }
+    return Optional.empty();
+  }
+
+}