Add stable Metrics class to decouple consumers from protobuf version

The generated protobuf Metrics.java lives in a versioned package that
changes every protobuf release, requiring import updates in all consumer
files. Introduce a stable extending class in the version-free package
so consumers import from a single stable location. On protobuf upgrades
only the extends clause in the stable class changes, handled
automatically by generate-protobuf.sh.

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Author: zeitlinger

CONTRIBUTING.md

@@ -58,10 +58,23 @@ mise run compile
 
 ## Updating the Protobuf Java Classes
 
+The generated protobuf `Metrics.java` lives in a versioned package
+(e.g., `...generated.com_google_protobuf_4_33_5`) that changes with each
+protobuf release. A stable extending class at
+`...generated/Metrics.java` reexports all types so that consumer code
+only imports from the version-free package. On protobuf upgrades only
+the `extends` clause in the stable class changes.
+
 In the failing PR from renovate, run:
 
 ```shell
 mise run generate
 ```
 
-Add the new `Metrics.java` to Git and commit it.
+The script will:
+
+1. Re-generate the protobuf sources with the new version.
+2. Update the versioned package name in all Java files
+   (including the stable `Metrics.java` extends clause).
+
+Add the updated files to Git and commit them.

prometheus-metrics-exposition-formats/generate-protobuf.sh

@@ -18,7 +18,7 @@ mkdir -p "$TARGET_DIR"
 rm -rf $PROTO_DIR || true
 mkdir -p $PROTO_DIR
 
-OLD_PACKAGE=$(sed -nE 's/import (io.prometheus.metrics.expositionformats.generated.*).Metrics;/\1/p' src/main/java/io/prometheus/metrics/expositionformats/internal/PrometheusProtobufWriterImpl.java)
+OLD_PACKAGE=$(sed -nE 's/.*extends (io\.prometheus\.metrics\.expositionformats\.generated\.[^ ]*?)\.Metrics.*/\1/p' src/main/java/io/prometheus/metrics/expositionformats/generated/Metrics.java)
 PACKAGE="io.prometheus.metrics.expositionformats.generated.com_google_protobuf_${PROTOBUF_VERSION_STRING}"
 
 if [[ $OLD_PACKAGE != "$PACKAGE" ]]; then
@@ -33,6 +33,10 @@ protoc --java_out "$TARGET_DIR" $PROTO_DIR/metrics.proto
 sed -i '1 i\//CHECKSTYLE:OFF: checkstyle' "$(find src/main/generated/io -type f)"
 sed -i -e $'$a\\\n//CHECKSTYLE:ON: checkstyle' "$(find src/main/generated/io -type f)"
 
+GENERATED_FILE="$TARGET_DIR/${PACKAGE//\.//}/Metrics.java"
+sed -i 's/public final class Metrics/public class Metrics/' "$GENERATED_FILE"
+sed -i 's/private Metrics() {}/protected Metrics() {}/' "$GENERATED_FILE"
+
 GENERATED_WITH=$(grep -oP '\/\/ Protobuf Java Version: \K.*' "$TARGET_DIR/${PACKAGE//\.//}"/Metrics.java)
 
 function help() {

prometheus-metrics-exposition-formats/src/main/generated/io/prometheus/metrics/expositionformats/generated/com_google_protobuf_4_33_5/Metrics.java

@@ -0,0 +1,6 @@
+package io.prometheus.metrics.expositionformats.generated;
+
+public final class Metrics
+    extends io.prometheus.metrics.expositionformats.generated.com_google_protobuf_4_33_5.Metrics {
+  private Metrics() {}
+}

prometheus-metrics-exposition-formats/src/main/java/io/prometheus/metrics/expositionformats/generated/Metrics.java

@@ -7,7 +7,7 @@
 import io.prometheus.metrics.config.EscapingScheme;
 import io.prometheus.metrics.expositionformats.ExpositionFormatWriter;
 import io.prometheus.metrics.expositionformats.TextFormatUtil;
-import io.prometheus.metrics.expositionformats.generated.com_google_protobuf_4_33_5.Metrics;
+import io.prometheus.metrics.expositionformats.generated.Metrics;
 import io.prometheus.metrics.model.snapshots.ClassicHistogramBuckets;
 import io.prometheus.metrics.model.snapshots.CounterSnapshot;
 import io.prometheus.metrics.model.snapshots.CounterSnapshot.CounterDataPointSnapshot;
@@ -30,6 +30,7 @@
 import java.io.OutputStream;
 import javax.annotation.Nullable;
 
+@SuppressWarnings("NonCanonicalType")
 public class PrometheusProtobufWriterImpl implements ExpositionFormatWriter {
 
   @Override

prometheus-metrics-exposition-formats/src/main/java/io/prometheus/metrics/expositionformats/internal/PrometheusProtobufWriterImpl.java

@@ -3,7 +3,7 @@
 import static org.assertj.core.api.Assertions.assertThat;
 
 import io.prometheus.metrics.config.EscapingScheme;
-import io.prometheus.metrics.expositionformats.generated.com_google_protobuf_4_33_5.Metrics;
+import io.prometheus.metrics.expositionformats.generated.Metrics;
 import io.prometheus.metrics.expositionformats.internal.PrometheusProtobufWriterImpl;
 import io.prometheus.metrics.model.registry.Collector;
 import io.prometheus.metrics.model.registry.PrometheusRegistry;
@@ -19,6 +19,7 @@
 import java.util.List;
 import org.junit.jupiter.api.Test;
 
+@SuppressWarnings("NonCanonicalType")
 class DuplicateNamesProtobufTest {
 
   private static PrometheusRegistry getPrometheusRegistry() {

prometheus-metrics-exposition-formats/src/test/java/io/prometheus/metrics/expositionformats/DuplicateNamesProtobufTest.java

@@ -3,11 +3,12 @@
 import static org.assertj.core.api.Assertions.assertThat;
 
 import io.prometheus.metrics.config.EscapingScheme;
-import io.prometheus.metrics.expositionformats.generated.com_google_protobuf_4_33_5.Metrics;
+import io.prometheus.metrics.expositionformats.generated.Metrics;
 import io.prometheus.metrics.expositionformats.internal.PrometheusProtobufWriterImpl;
 import io.prometheus.metrics.expositionformats.internal.ProtobufUtil;
 import io.prometheus.metrics.model.snapshots.MetricSnapshot;
 
+@SuppressWarnings("NonCanonicalType")
 class ProtobufExpositionFormatsTest extends ExpositionFormatsTest {
 
   @Override