feat: report runtime info

codegen/internal/generator/params.go

@@ -12,6 +12,7 @@ import (
 type Params struct {
 	SpecPath    string
 	OutputDir   string
+	ResourceDir string
 	BasePackage string
 }
 
@@ -34,6 +35,12 @@ func (p *Params) normalize() error {
 	if p.OutputDir, err = filepath.Abs(p.OutputDir); err != nil {
 		return fmt.Errorf("resolve output directory: %w", err)
 	}
+	if p.ResourceDir == "" {
+		p.ResourceDir = filepath.Join(filepath.Dir(p.OutputDir), "resources")
+	}
+	if p.ResourceDir, err = filepath.Abs(p.ResourceDir); err != nil {
+		return fmt.Errorf("resolve resource directory: %w", err)
+	}
 	return nil
 }
 
@@ -55,6 +62,18 @@ func (p *Params) validate() error {
 	} else if !fi.IsDir() {
 		return fmt.Errorf("output directory %s is not a directory", p.OutputDir)
 	}
+	fi, err = os.Stat(p.ResourceDir)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			if err := os.MkdirAll(p.ResourceDir, 0o755); err != nil {
+				return fmt.Errorf("create resource directory: %w", err)
+			}
+		} else {
+			return fmt.Errorf("resource directory: %w", err)
+		}
+	} else if !fi.IsDir() {
+		return fmt.Errorf("resource directory %s is not a directory", p.ResourceDir)
+	}
 	return nil
 }
 

codegen/internal/generator/resources.go

@@ -0,0 +1,24 @@
+package generator
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+func renderApiVersionResource(apiVersion string, params Params) error {
+	apiVersion = strings.TrimSpace(apiVersion)
+	if apiVersion == "" {
+		return fmt.Errorf("missing api version in spec info")
+	}
+	targetDir := filepath.Join(params.ResourceDir, params.basePackagePath())
+	if err := os.MkdirAll(targetDir, 0o755); err != nil {
+		return fmt.Errorf("create api version resource directory: %w", err)
+	}
+	target := filepath.Join(targetDir, "api-version.txt")
+	if err := os.WriteFile(target, []byte(apiVersion), 0o644); err != nil {
+		return fmt.Errorf("write api version resource: %w", err)
+	}
+	return nil
+}

codegen/internal/generator/run.go

@@ -32,6 +32,11 @@ func Run(ctx context.Context, params Params) error {
 		return err
 	}
 
+	apiVersion := ""
+	if doc.Info != nil {
+		apiVersion = doc.Info.Version
+	}
+
 	slog.Info("Generating SDK", "spec", params.SpecPath)
 	if err := renderClients(model, params); err != nil {
 		return err
@@ -42,6 +47,9 @@ func Run(ctx context.Context, params Params) error {
 	if err := renderSumUpClient(model, params); err != nil {
 		return err
 	}
+	if err := renderApiVersionResource(apiVersion, params); err != nil {
+		return err
+	}
 
 	return nil
 }

src/build.gradle

@@ -21,7 +21,7 @@ sourceSets {
     def emptyDirs = []
     main {
         java.srcDirs = ['main/java']
-        resources.srcDirs = emptyDirs
+        resources.srcDirs = ['main/resources']
     }
     test {
         java.srcDirs = ['test/java']

src/main/java/com/sumup/sdk/core/ApiClient.java

@@ -186,6 +186,7 @@ private void applyHeaders(
       RequestOptions requestOptions) {
     Map<String, String> merged = new LinkedHashMap<>();
     merged.put("User-Agent", SdkMetadata.userAgent());
+    merged.putAll(SdkMetadata.runtimeHeaders());
     if (headerParams != null) {
       headerParams.forEach(
           (name, value) -> {

src/main/java/com/sumup/sdk/core/SdkMetadata.java

@@ -3,20 +3,38 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.nio.charset.StandardCharsets;
+import java.util.Map;
 
 /**
  * Provides metadata about the SDK that can be attached to outgoing requests, such as the current
  * version and the default {@code User-Agent} header value.
  */
 public final class SdkMetadata {
+  private static final String API_VERSION_RESOURCE = "/com/sumup/sdk/api-version.txt";
   private static final String VERSION_RESOURCE = "/com/sumup/sdk/sdk-version.txt";
   private static final String USER_AGENT_PREFIX = "sumup-java";
+  private static final String LANGUAGE = "java";
 
-  private static final String VERSION = loadVersion();
+  private static final String API_VERSION = loadResource(API_VERSION_RESOURCE);
+  private static final String VERSION = loadResource(VERSION_RESOURCE);
   private static final String USER_AGENT = USER_AGENT_PREFIX + "/v" + VERSION;
+  private static final Map<String, String> RUNTIME_HEADERS =
+      Map.of(
+          "X-Sumup-Api-Version", API_VERSION,
+          "X-Sumup-Lang", LANGUAGE,
+          "X-Sumup-Package-Version", VERSION,
+          "X-Sumup-OS", System.getProperty("os.name", "unknown"),
+          "X-Sumup-Arch", runtimeArch(),
+          "X-Sumup-Runtime", runtimeIdentifier(),
+          "X-Sumup-Runtime-Version", Runtime.version().toString());
 
   private SdkMetadata() {}
 
+  /** Returns the API version declared by the OpenAPI specification. */
+  public static String apiVersion() {
+    return API_VERSION;
+  }
+
   /** Returns the SDK version read from the generated version resource. */
   public static String version() {
     return VERSION;
@@ -27,8 +45,28 @@ public static String userAgent() {
     return USER_AGENT;
   }
 
-  private static String loadVersion() {
-    try (InputStream stream = SdkMetadata.class.getResourceAsStream(VERSION_RESOURCE)) {
+  /** Returns the runtime headers that should be sent with each request. */
+  public static Map<String, String> runtimeHeaders() {
+    return RUNTIME_HEADERS;
+  }
+
+  static String runtimeArch() {
+    String arch = System.getProperty("os.arch", "unknown").toLowerCase();
+    return switch (arch) {
+      case "amd64", "x86_64" -> "x86_64";
+      case "x86", "i386", "i486", "i586", "i686" -> "x86";
+      case "aarch64", "arm64" -> "arm64";
+      case "arm", "armv7", "armv7l" -> "arm";
+      default -> arch;
+    };
+  }
+
+  private static String runtimeIdentifier() {
+    return LANGUAGE + Runtime.version();
+  }
+
+  private static String loadResource(String path) {
+    try (InputStream stream = SdkMetadata.class.getResourceAsStream(path)) {
       if (stream == null) {
         return "unknown";
       }

src/main/resources/com/sumup/sdk/api-version.txt

@@ -0,0 +1 @@
+1.0.0

src/test/java/com/sumup/sdk/core/ApiClientTest.java

@@ -74,6 +74,27 @@ void requestOptionsCanOverrideUserAgent() {
         "custom/agent", httpClient.lastRequest().headers().firstValue("User-Agent").orElse(null));
   }
 
+  @Test
+  void defaultRuntimeHeadersAreIncluded() {
+    CapturingHttpClient httpClient = new CapturingHttpClient();
+    ApiClient client = ApiClient.builder().httpClient(httpClient).build();
+
+    client.send(HttpMethod.GET, "/v1/test", null, null, null, null, null);
+
+    HttpHeaders headers = httpClient.lastRequest().headers();
+    assertEquals(SdkMetadata.apiVersion(), headers.firstValue("X-Sumup-Api-Version").orElse(null));
+    assertEquals("java", headers.firstValue("X-Sumup-Lang").orElse(null));
+    assertEquals(SdkMetadata.version(), headers.firstValue("X-Sumup-Package-Version").orElse(null));
+    assertEquals(
+        System.getProperty("os.name", "unknown"), headers.firstValue("X-Sumup-OS").orElse(null));
+    assertEquals(
+        SdkMetadata.runtimeHeaders().get("X-Sumup-Arch"),
+        headers.firstValue("X-Sumup-Arch").orElse(null));
+    assertEquals("java" + Runtime.version(), headers.firstValue("X-Sumup-Runtime").orElse(null));
+    assertEquals(
+        Runtime.version().toString(), headers.firstValue("X-Sumup-Runtime-Version").orElse(null));
+  }
+
   @Test
   void requestOptionsCanOverrideTimeout() {
     CapturingHttpClient httpClient = new CapturingHttpClient();