SCANJLIB-169 Rework the API to support functional errors

The bootstrapper now returns a result with a boolean allowing the caller to terminate without throwing an exception.
This is used to log auth errors, but it may be also useful for other functional errors.

Author: henryju

its/it-simple-scanner/src/main/java/com/sonar/scanner/lib/it/Main.java

@@ -21,11 +21,13 @@
 
 import java.util.HashMap;
 import java.util.Map;
+import java.util.concurrent.atomic.AtomicBoolean;
 import org.sonarsource.scanner.lib.EnvironmentConfig;
 import org.sonarsource.scanner.lib.ScannerEngineBootstrapper;
 
 public class Main {
   public static void main(String[] args) {
+    AtomicBoolean success = new AtomicBoolean(false);
     try {
 
       Map<String, String> props = new HashMap<>(EnvironmentConfig.load());
@@ -36,20 +38,25 @@ public static void main(String[] args) {
         }
       }
 
-      runProject(props);
+      success.set(runScanner(props));
     } catch (Exception e) {
       e.printStackTrace();
-      System.exit(1);
+      System.exit(2);
     }
-    System.exit(0);
+    System.exit(success.get() ? 0 : 1);
   }
 
-  private static void runProject(Map<String, String> props) throws Exception {
+  private static boolean runScanner(Map<String, String> props) throws Exception {
 
-    try (var scannerEngine = ScannerEngineBootstrapper.create("Simple Scanner", "1.0")
+    try (var bootstrapResult = ScannerEngineBootstrapper.create("Simple Scanner", "1.0")
       .addBootstrapProperties(props)
       .bootstrap()) {
-      scannerEngine.analyze(props);
+      if (bootstrapResult.isSuccessful()) {
+        bootstrapResult.getEngineFacade().analyze(props);
+        return true;
+      } else {
+        return false;
+      }
     }
   }
 }

its/it-tests/src/test/java/com/sonar/scanner/lib/it/ProxyTest.java

@@ -206,7 +206,7 @@ public void simple_analysis_with_proxy_auth() throws Exception {
     params.put("sonar.scanner.proxyPort", "" + httpProxyPort);
 
     BuildResult buildResult = scanner.executeSimpleProject(project("js-sample"), ORCHESTRATOR.getServer().getUrl(), params, Map.of());
-    assertThat(buildResult.getLastStatus()).isEqualTo(1);
+    assertThat(buildResult.getLastStatus()).isNotZero();
     assertThat(buildResult.getLogs()).contains("Error status returned by url", ": 407");
     assertThat(seenByProxy).isEmpty();
 

its/it-tests/src/test/java/com/sonar/scanner/lib/it/SSLTest.java

@@ -218,7 +218,7 @@ public void simple_analysis_with_server_and_without_client_certificate_is_failin
     // Voluntary missing client keystore
 
     buildResult = scanner.executeSimpleProject(project("js-sample"), "https://localhost:" + httpsPort, params, Map.of());
-    assertThat(buildResult.getLastStatus()).isEqualTo(1);
+    assertThat(buildResult.getLastStatus()).isNotZero();
 
     // different exception is thrown depending on the JDK version. See: https://bugs.java.com/bugdatabase/view_bug.do?bug_id=8172163
     String failedAnalysis = "(?s).*java\\.lang\\.IllegalStateException: Failed to get server version.*";

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

@@ -40,7 +40,7 @@ public class EnvironmentConfig {
   private static final String GENERIC_ENV_PREFIX = "SONAR_SCANNER_";
   private static final String SONAR_HOST_URL_ENV_VAR = "SONAR_HOST_URL";
   private static final String SONAR_USER_HOME_ENV_VAR = "SONAR_USER_HOME";
-  private static final String TOKEN_ENV_VARIABLE = "SONAR_TOKEN";
+  static final String TOKEN_ENV_VARIABLE = "SONAR_TOKEN";
 
   private EnvironmentConfig() {
     // only static methods

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

@@ -0,0 +1,41 @@
+/*
+ * SonarScanner Java Library
+ * Copyright (C) 2011-2024 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;
+
+/**
+ * Closing this will automatically close the {@link ScannerEngineFacade} that it contains, if any.
+ */
+public interface ScannerEngineBootstrapResult extends AutoCloseable {
+
+  /**
+   * Allow to test if the bootstrapping has been successful. If not, the {@link ScannerEngineFacade} should not be used.
+   * A log message should have been emitted in case of failure.
+   *
+   * @return true if the bootstrapping has been successful, false otherwise
+   */
+  boolean isSuccessful();
+
+  /**
+   * Get the facade to interact with the engine. Only call this method if {@link #isSuccessful()} returns true.
+   *
+   * @return the facade to interact with the engine
+   */
+  ScannerEngineFacade getEngineFacade();
+}

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

@@ -33,14 +33,17 @@
 import org.apache.commons.lang3.StringUtils;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+import org.sonarsource.scanner.lib.internal.FailedBootstrap;
 import org.sonarsource.scanner.lib.internal.InternalProperties;
+import org.sonarsource.scanner.lib.internal.SuccessfulBootstrap;
 import org.sonarsource.scanner.lib.internal.cache.FileCache;
 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;
 import org.sonarsource.scanner.lib.internal.facade.inprocess.IsolatedLauncherFactory;
 import org.sonarsource.scanner.lib.internal.facade.simulation.SimulationScannerEngineFacade;
 import org.sonarsource.scanner.lib.internal.http.HttpConfig;
+import org.sonarsource.scanner.lib.internal.http.HttpException;
 import org.sonarsource.scanner.lib.internal.http.ScannerHttpClient;
 import org.sonarsource.scanner.lib.internal.http.ssl.CertificateStore;
 import org.sonarsource.scanner.lib.internal.util.ArchResolver;
@@ -111,10 +114,7 @@ public ScannerEngineBootstrapper setBootstrapProperty(String key, String value)
     return this;
   }
 
-  /**
-   * Bootstrap the scanner-engine.
-   */
-  public ScannerEngineFacade bootstrap() {
+  public ScannerEngineBootstrapResult bootstrap() {
     if (LOG.isDebugEnabled()) {
       LOG.debug("Scanner max available memory: {}", FileUtils.byteCountToDisplaySize(Runtime.getRuntime().maxMemory()));
     }
@@ -125,22 +125,52 @@ public ScannerEngineFacade bootstrap() {
     var isSimulation = immutableProperties.containsKey(InternalProperties.SCANNER_DUMP_TO_FILE);
     var sonarUserHome = resolveSonarUserHome(immutableProperties);
     var fileCache = FileCache.create(sonarUserHome);
-    var httpConfig = new HttpConfig(immutableProperties, sonarUserHome);
-    scannerHttpClient.init(httpConfig);
-    String serverVersion = null;
-    if (!isSonarCloud) {
-      serverVersion = getServerVersion(scannerHttpClient, isSimulation, immutableProperties);
-    }
 
     if (isSimulation) {
-      return new SimulationScannerEngineFacade(immutableProperties, isSonarCloud, serverVersion);
-    } else if (isSonarCloud || VersionUtils.isAtLeastIgnoringQualifier(serverVersion, SQ_VERSION_NEW_BOOTSTRAPPING)) {
-      var launcher = scannerEngineLauncherFactory.createLauncher(scannerHttpClient, fileCache, immutableProperties);
-      return new NewScannerEngineFacade(immutableProperties, launcher, isSonarCloud, serverVersion);
+      var serverVersion = immutableProperties.getOrDefault(InternalProperties.SCANNER_VERSION_SIMULATION, "9.9");
+      return new SuccessfulBootstrap(new SimulationScannerEngineFacade(immutableProperties, isSonarCloud, serverVersion));
+    }
+
+    // No HTTP call should be made before this point
+    try {
+      var httpConfig = new HttpConfig(immutableProperties, sonarUserHome);
+      scannerHttpClient.init(httpConfig);
+
+      var serverVersion = !isSonarCloud ? getServerVersion(scannerHttpClient) : null;
+      if (isSonarCloud || VersionUtils.isAtLeastIgnoringQualifier(serverVersion, SQ_VERSION_NEW_BOOTSTRAPPING)) {
+        var launcher = scannerEngineLauncherFactory.createLauncher(scannerHttpClient, fileCache, immutableProperties);
+        return new SuccessfulBootstrap(new NewScannerEngineFacade(immutableProperties, launcher, isSonarCloud, serverVersion));
+      } else {
+        var launcher = launcherFactory.createLauncher(scannerHttpClient, fileCache);
+        var adaptedProperties = adaptDeprecatedPropertiesForInProcessBootstrapping(immutableProperties, httpConfig);
+        return new SuccessfulBootstrap(new InProcessScannerEngineFacade(adaptedProperties, launcher, false, serverVersion));
+      }
+    } catch (RuntimeException e) {
+      return handleException(e);
+    }
+  }
+
+  private static ScannerEngineBootstrapResult handleException(RuntimeException e) {
+    if (e instanceof HttpException) {
+      var httpEx = (HttpException) e;
+      if (httpEx.getCode() == 401 || httpEx.getCode() == 403) {
+        var message = httpEx.getMessage() + ". Please check the property " + ScannerProperties.SONAR_TOKEN +
+          " or the environment variable " + EnvironmentConfig.TOKEN_ENV_VARIABLE + ".";
+        logWithStacktraceOnlyIfDebug(message, e);
+        return new FailedBootstrap();
+      }
+    }
+    throw e;
+  }
+
+  /**
+   * For functional errors, the stacktrace is not necessary. It is only useful for debugging.
+   */
+  private static void logWithStacktraceOnlyIfDebug(String message, Throwable t) {
+    if (LOG.isDebugEnabled()) {
+      LOG.error(message, t);
     } else {
-      var launcher = launcherFactory.createLauncher(scannerHttpClient, fileCache);
-      var adaptedProperties = adaptDeprecatedPropertiesForInProcessBootstrapping(immutableProperties, httpConfig);
-      return new InProcessScannerEngineFacade(adaptedProperties, launcher, false, serverVersion);
+      LOG.error(message);
     }
   }
 
@@ -195,14 +225,14 @@ private static Path resolveSonarUserHome(Map<String, String> properties) {
     return Paths.get(sonarUserHome);
   }
 
-  private static String getServerVersion(ScannerHttpClient scannerHttpClient, boolean isSimulation, Map<String, String> properties) {
-    if (isSimulation) {
-      return properties.getOrDefault(InternalProperties.SCANNER_VERSION_SIMULATION, "5.6");
-    }
-
+  private static String getServerVersion(ScannerHttpClient scannerHttpClient) {
     try {
       return scannerHttpClient.callRestApi("/analysis/version");
     } catch (Exception e) {
+      if (e instanceof HttpException && (((HttpException) e).getCode() == 401 || ((HttpException) e).getCode() == 403)) {
+        throw (HttpException) e;
+      }
+
       try {
         return scannerHttpClient.callWebApi("/api/server/version");
       } catch (Exception e2) {

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

@@ -21,7 +21,6 @@
 
 import java.util.Map;
 
-
 public interface ScannerEngineFacade extends AutoCloseable {
 
   /**

lib/src/main/java/org/sonarsource/scanner/lib/internal/FailedBootstrap.java

@@ -0,0 +1,41 @@
+/*
+ * SonarScanner Java Library
+ * Copyright (C) 2011-2024 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;
+
+import org.sonarsource.scanner.lib.ScannerEngineBootstrapResult;
+import org.sonarsource.scanner.lib.ScannerEngineFacade;
+
+public class FailedBootstrap implements ScannerEngineBootstrapResult {
+
+  @Override
+  public boolean isSuccessful() {
+    return false;
+  }
+
+  @Override
+  public ScannerEngineFacade getEngineFacade() {
+    throw new UnsupportedOperationException("No engine facade available");
+  }
+
+  @Override
+  public void close() {
+    // No operation
+  }
+}

lib/src/main/java/org/sonarsource/scanner/lib/internal/SuccessfulBootstrap.java

@@ -0,0 +1,47 @@
+/*
+ * SonarScanner Java Library
+ * Copyright (C) 2011-2024 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;
+
+import org.sonarsource.scanner.lib.ScannerEngineBootstrapResult;
+import org.sonarsource.scanner.lib.ScannerEngineFacade;
+
+public class SuccessfulBootstrap implements ScannerEngineBootstrapResult {
+
+  private final ScannerEngineFacade facade;
+
+  public SuccessfulBootstrap(ScannerEngineFacade facade) {
+    this.facade = facade;
+  }
+
+  @Override
+  public boolean isSuccessful() {
+    return true;
+  }
+
+  @Override
+  public ScannerEngineFacade getEngineFacade() {
+    return facade;
+  }
+
+  @Override
+  public void close() throws Exception {
+    facade.close();
+  }
+}

lib/src/main/java/org/sonarsource/scanner/lib/internal/http/HttpException.java

@@ -0,0 +1,50 @@
+/*
+ * SonarScanner Java Library
+ * Copyright (C) 2011-2024 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.http;
+
+import java.net.URL;
+import javax.annotation.Nullable;
+
+public class HttpException extends RuntimeException {
+  private final URL requestUrl;
+  private final int code;
+  @Nullable
+  private final String body;
+
+  public HttpException(URL requestUrl, int code, String message, @Nullable String body) {
+    super(message);
+    this.requestUrl = requestUrl;
+    this.code = code;
+    this.body = body;
+  }
+
+  public URL getRequestUrl() {
+    return requestUrl;
+  }
+
+  public int getCode() {
+    return code;
+  }
+
+  @Nullable
+  public String getBody() {
+    return body;
+  }
+}