Merge branch 'main' into orchestration-convenience/typed-model-parameters

Author: newtork

.github/workflows/e2e-test.yaml

@@ -2,16 +2,24 @@ name: "End-to-end Tests"
 on:
   workflow_dispatch:
   schedule:
-    - cron: 0 2 * * *
+    - cron: 15 2 * * MON-FRI
 
 env:
   MVN_MULTI_THREADED_ARGS: --batch-mode --no-transfer-progress --fail-at-end --show-version --threads 1C
   JAVA_VERSION: 17
 
 jobs:
-
   end-to-end-tests:
-    # https://wiki.one.int.sap/wiki/display/DevFw/SUGAR
+    strategy:
+      fail-fast: false
+      matrix:
+        environment: [ canary, production ]
+        exclude:
+          - environment: production
+            # secret-name: AI_CORE_PRODUCTION
+        include:
+          - environment: canary
+            secret-name: AI_CORE_CANARY
     runs-on: ubuntu-latest
     steps:
 
@@ -33,10 +41,10 @@ jobs:
       - name: "Run tests"
         run: |
           MVN_ARGS="${{ env.MVN_MULTI_THREADED_ARGS }} surefire:test -pl :spring-app -DskipTests=false"
-          mvn $MVN_ARGS
+          mvn $MVN_ARGS "-Daicore.landscape=${{ matrix.environment }}"
         env:
           # See "End-to-end test application instructions" on the README.md to update the secret
-          AICORE_SERVICE_KEY: ${{ secrets.AICORE_SERVICE_KEY }}
+          AICORE_SERVICE_KEY: ${{ secrets[matrix.secret-name] }}
 
       - name: "Start Application Locally"
         run: |
@@ -53,7 +61,7 @@ jobs:
           done
         env:
           # See "End-to-end test application instructions" on the README.md to update the secret
-          AICORE_SERVICE_KEY: ${{ secrets.AICORE_SERVICE_KEY }}
+          AICORE_SERVICE_KEY: ${{ secrets[matrix.secret-name] }}
 
       - name: "Health Check"
         # print response body with headers to stdout.  q:body only  O:print  -:stdout  S:headers

.github/workflows/fosstars-report.yml

@@ -22,6 +22,12 @@ jobs:
           distribution: "temurin"
           java-version: ${{ env.JAVA_VERSION }}
           cache: 'maven'
+      - name: Restore CVE Database
+        uses: actions/cache/restore@v4
+        with:
+          path: ${{ env.CVE_CACHE_DIR }}
+          key: ${{ env.CVE_CACHE_KEY }}
+          fail-on-cache-miss: true
 
       - name: "Build SDK"
         run: |

.github/workflows/update-vulnerability-database.yaml

@@ -0,0 +1,62 @@
+name: Update Vulnerability Database
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '42 03 * * MON-FRI' # 03:42 on weekdays, a somewhat random time to avoid producing load spikes on the GH actions infrastructure
+
+env:
+  CVE_CACHE_REF: refs/heads/main
+  CVE_CACHE_KEY: cve-db
+  CVE_CACHE_DIR: ~/.m2/repository/org/owasp/dependency-check-data
+
+jobs:
+  update-vulnerability-database:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ env.CVE_CACHE_REF }}
+      - name: Restore Existing Cache
+        uses: actions/cache/restore@v4
+        with:
+          path: ${{ env.CVE_CACHE_DIR }}
+          key: ${{ env.CVE_CACHE_KEY }}
+
+      - name: Run Maven Plugin
+        run: |
+          mvn org.owasp:dependency-check-maven:10.0.4:update-only -DnvdMaxRetryCount=10 -DnvdApiDelay=15000 -DconnectionTimeout=60000
+        env:
+          NVD_API_KEY: ${{ secrets.NVD_API_KEY }}
+
+      - name: Delete Cache
+        run: |
+          CACHE_IDS=$(gh cache list --key "${{ env.CVE_CACHE_KEY }}" --ref "${{ env.CVE_CACHE_REF }}" --json id | jq -r '.[] | .id')
+          for CACHE_ID in $CACHE_IDS; do
+              echo "Deleting cache with ID: $CACHE_ID"
+              gh cache delete "${CACHE_ID}"
+          done
+        env:
+          GH_TOKEN: ${{ secrets.CLOUD_SDK_AT_SAP_ALL_ACCESS_PAT }}
+
+      - name: Cache CVE Database
+        uses: actions/cache/save@v4
+        with:
+          path: ${{ env.CVE_CACHE_DIR }}
+          key: ${{ env.CVE_CACHE_KEY }}
+
+      # - name: "Slack Notification"
+      #   if: failure()
+      #   uses: slackapi/[email protected]
+      #   with:
+      #     payload: |
+      #       {
+      #         "text": "⚠️ OWASP Update Failed! 😬 Please inspect & fix by clicking <https://github.com/SAP/ai-sdk-java/actions/runs/${{ github.run_id }}|here>"
+      #       }
+      #   env:
+      #     SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}
+      #     SLACK_WEBHOOK_TYPE: INCOMING_WEBHOOK
+
+

README.md

@@ -37,15 +37,21 @@ The SDK simplifies the setup and interaction with SAP AI Core, allowing you to f
 
 ## General Requirements
 
-To use the SAP AI SDK for Java, the following general prerequisites must be met:
+To use the SDK in a Java application, it is necessary to understand the technical prerequisites and required versions for common dependencies.
 
-- **Java Development Kit (JDK) 17** or higher installed.
-- **Apache Maven 3.9** or higher installed.
 - **SAP AI Core Service** enabled in your SAP BTP account.
     - [How to enable the AI Core service](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/initial-setup)
 - **SAP AI Core Credentials** to access the AI Core service.
     - [Connecting to SAP AI Core](#connecting-to-sap-ai-core)
-- **(Optional) Spring Boot** version 3 or higher if you are using Spring Boot.
+
+The following table lists the required versions, based on the latest release:
+
+| Dependency | Minimum Version | Recommended Version |
+| --- | --- | --- |
+| JDK | 17 (LTS) | 21 (LTS) |
+| SAP Cloud SDK | 5.6.0 | latest |
+| (optional) CAP Java | 3.0.0 | latest |
+| (optional) Spring Boot | 3.0 | latest |
 
 See [an example `pom.xml` in our Spring Boot application](sample-code/spring-app/pom.xml).
 

core/pom.xml

@@ -157,6 +157,8 @@
             <groupId>com.sap.cloud.sdk.datamodel</groupId>
             <artifactId>openapi-generator-maven-plugin</artifactId>
             <configuration>
+              <skip>true</skip>
+              <!-- TODO: remove this once Cloud SDK 5.15.0 is released -->
               <outputDirectory>${project.basedir}/src/main/java</outputDirectory>
               <apiMaturity>released</apiMaturity>
               <enableOneOfAnyOfGeneration>true</enableOneOfAnyOfGeneration>

core/src/main/java/com/sap/ai/sdk/core/AiCoreCredentialsInvalidException.java

@@ -0,0 +1,7 @@
+package com.sap.ai.sdk.core;
+
+import lombok.experimental.StandardException;
+
+/** Exception thrown when the JSON AI Core service key is invalid. */
+@StandardException
+class AiCoreCredentialsInvalidException extends RuntimeException {}

core/src/main/java/com/sap/ai/sdk/core/AiCoreDeployment.java

@@ -1,6 +1,6 @@
 package com.sap.ai.sdk.core;
 
-import com.sap.cloud.sdk.cloudplatform.connectivity.Destination;
+import com.sap.cloud.sdk.cloudplatform.connectivity.HttpDestination;
 import com.sap.cloud.sdk.cloudplatform.connectivity.exception.DestinationAccessException;
 import com.sap.cloud.sdk.cloudplatform.connectivity.exception.DestinationNotFoundException;
 import com.sap.cloud.sdk.services.openapi.apiclient.ApiClient;
@@ -30,7 +30,8 @@ public AiCoreDeployment withResourceGroup(@Nonnull final String resourceGroup) {
 
   @Nonnull
   @Override
-  public Destination destination() throws DestinationAccessException, DestinationNotFoundException {
+  public HttpDestination destination()
+      throws DestinationAccessException, DestinationNotFoundException {
     aiCoreService.deploymentId = deploymentId.get();
     return aiCoreService.destination();
   }

core/src/main/java/com/sap/ai/sdk/core/AiCoreService.java

@@ -1,8 +1,5 @@
 package com.sap.ai.sdk.core;
 
-import static com.sap.ai.sdk.core.DestinationResolver.AI_CLIENT_TYPE_KEY;
-import static com.sap.ai.sdk.core.DestinationResolver.AI_CLIENT_TYPE_VALUE;
-
 import com.fasterxml.jackson.annotation.JsonAutoDetect;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.PropertyAccessor;
@@ -12,15 +9,14 @@
 import com.sap.cloud.sdk.cloudplatform.connectivity.DefaultHttpDestination;
 import com.sap.cloud.sdk.cloudplatform.connectivity.Destination;
 import com.sap.cloud.sdk.cloudplatform.connectivity.DestinationProperty;
+import com.sap.cloud.sdk.cloudplatform.connectivity.HttpDestination;
 import com.sap.cloud.sdk.cloudplatform.connectivity.exception.DestinationAccessException;
 import com.sap.cloud.sdk.cloudplatform.connectivity.exception.DestinationNotFoundException;
 import com.sap.cloud.sdk.services.openapi.apiclient.ApiClient;
-import io.github.cdimascio.dotenv.Dotenv;
 import java.util.NoSuchElementException;
 import java.util.function.BiFunction;
 import java.util.function.Function;
 import javax.annotation.Nonnull;
-import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import lombok.val;
 import org.springframework.http.client.BufferingClientHttpRequestFactory;
@@ -31,19 +27,21 @@
 
 /** Connectivity convenience methods for AI Core. */
 @Slf4j
-@RequiredArgsConstructor
 public class AiCoreService implements AiCoreDestination {
-
-  Function<AiCoreService, Destination> baseDestinationHandler;
-  final BiFunction<AiCoreService, Destination, ApiClient> clientHandler;
-  final BiFunction<AiCoreService, Destination, DefaultHttpDestination.Builder> builderHandler;
+  static final String AI_CLIENT_TYPE_KEY = "URL.headers.AI-Client-Type";
+  static final String AI_CLIENT_TYPE_VALUE = "AI SDK Java";
+  static final String AI_RESOURCE_GROUP = "URL.headers.AI-Resource-Group";
 
   private static final DeploymentCache DEPLOYMENT_CACHE = new DeploymentCache();
 
-  private static final String AI_RESOURCE_GROUP = "URL.headers.AI-Resource-Group";
+  @Nonnull private final DestinationResolver destinationResolver;
 
-  /** loads the .env file from the root of the project */
-  private static final Dotenv DOTENV = Dotenv.configure().ignoreIfMissing().load();
+  @Nonnull private Function<AiCoreService, HttpDestination> baseDestinationHandler;
+  @Nonnull private final BiFunction<AiCoreService, HttpDestination, ApiClient> clientHandler;
+
+  @Nonnull
+  private final BiFunction<AiCoreService, HttpDestination, DefaultHttpDestination.Builder>
+      builderHandler;
 
   /** The resource group is defined by AiCoreDeployment.withResourceGroup(). */
   @Nonnull String resourceGroup;
@@ -53,8 +51,16 @@ public class AiCoreService implements AiCoreDestination {
 
   /** The default constructor. */
   public AiCoreService() {
-    this(AiCoreService::getApiClient, AiCoreService::getDestinationBuilder, "default", "");
+    this(new DestinationResolver());
+  }
+
+  AiCoreService(@Nonnull final DestinationResolver destinationResolver) {
+    this.destinationResolver = destinationResolver;
     baseDestinationHandler = AiCoreService::getBaseDestination;
+    clientHandler = AiCoreService::buildApiClient;
+    builderHandler = AiCoreService::getDestinationBuilder;
+    resourceGroup = "default";
+    deploymentId = "";
   }
 
   @Nonnull
@@ -66,7 +72,7 @@ public ApiClient client() {
 
   @Nonnull
   @Override
-  public Destination destination() {
+  public HttpDestination destination() {
     val dest = baseDestinationHandler.apply(this);
     val builder = builderHandler.apply(this, dest);
     if (!deploymentId.isEmpty()) {
@@ -107,7 +113,7 @@ protected void destinationSetHeaders(@Nonnull final DefaultHttpDestination.Build
    * @return The AI Core Service based on the provided destination.
    */
   @Nonnull
-  public AiCoreService withDestination(@Nonnull final Destination destination) {
+  public AiCoreService withDestination(@Nonnull final HttpDestination destination) {
     baseDestinationHandler = service -> destination;
     return this;
   }
@@ -161,10 +167,9 @@ public AiCoreDeployment forDeploymentByScenario(@Nonnull final String scenarioId
    * @throws DestinationNotFoundException If the destination cannot be found.
    */
   @Nonnull
-  protected Destination getBaseDestination()
+  protected HttpDestination getBaseDestination()
       throws DestinationAccessException, DestinationNotFoundException {
-    val serviceKey = DOTENV.get("AICORE_SERVICE_KEY");
-    return DestinationResolver.getDestination(serviceKey);
+    return destinationResolver.getDestination();
   }
 
   /**
@@ -186,14 +191,13 @@ protected DefaultHttpDestination.Builder getDestinationBuilder(
   }
 
   /**
-   * Get a destination using the default service binding loading logic.
+   * Build an {@link ApiClient} that can be used for executing plain REST HTTP calls.
    *
-   * @return The destination.
-   * @throws DestinationAccessException If the destination cannot be accessed.
-   * @throws DestinationNotFoundException If the destination cannot be found.
+   * @param destination The destination to use as basis for the client.
+   * @return The new API client.
    */
   @Nonnull
-  protected ApiClient getApiClient(@Nonnull final Destination destination) {
+  protected ApiClient buildApiClient(@Nonnull final Destination destination) {
     val objectMapper =
         new Jackson2ObjectMapperBuilder()
             .modules(new JavaTimeModule())