feat: buffer unsent build metrics for offline store-and-forward

Metrics were lost whenever the endpoint was unreachable — exactly the
offline and flaky-connection builds we still want to capture. A failed
POST now parks the payload under the Gradle user home and the next build
that sends successfully flushes it.

MetricsPublisher distinguishes three send outcomes: accepted, unreachable
(worth retrying), and refused by a reachable endpoint (retrying will not
help, so the payload is dropped). Flushing drains oldest first and stops
as soon as the endpoint goes unreachable again, so a flaky connection
cannot turn into a burst of doomed requests.

UnsentMetricsBuffer caps the store at 200 payloads and seven days, and
swallows every I/O error. All of it stays off the build's critical path:
post() still returns immediately, and the returned future exists only so
tests can await the send without sleeping.

Closes #4

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dicko2

README.md

@@ -71,6 +71,11 @@ or delay the build.
 The default endpoint is `http://compilation-metrics/gradle`. Override it with the
 `BUILD_METRICS_ES_ENDPOINT` environment variable.
 
+When the endpoint is unreachable the payload is buffered under
+`<gradle user home>/kotlin-local-metrics/unsent-build-metrics` and flushed on the next
+build that sends successfully, so builds done offline are not lost. The buffer holds at
+most 200 payloads and discards anything older than seven days.
+
 ## Ktor startup metrics
 
 Add the module to a Ktor server and install the application plugin:

gradle-build-metrics-plugin/README.md

@@ -22,3 +22,16 @@ the build.
 
 The default endpoint is `http://compilation-metrics/gradle`. Override it with the
 `BUILD_METRICS_ES_ENDPOINT` environment variable.
+
+## Offline buffering
+
+When the endpoint cannot be reached — the developer is offline, the VPN is down, DNS
+fails — the payload is written to
+`<gradle user home>/kotlin-local-metrics/unsent-build-metrics` instead of being dropped.
+The next build whose send succeeds flushes those payloads and deletes each one as it
+is accepted, so builds done offline are not lost.
+
+The buffer is bounded: at most 200 payloads, and nothing older than seven days. Older
+entries beyond either cap are discarded. A payload that a reachable endpoint refuses is
+discarded rather than retried. All buffer I/O is off the build's critical path and, like
+the rest of collection, can never fail the build.

gradle-build-metrics-plugin/src/main/kotlin/io/agodadev/localmetrics/gradle/BuildMetricsPlugin.kt

@@ -1,5 +1,6 @@
 package io.agodadev.localmetrics.gradle
 
+import java.io.File
 import javax.inject.Inject
 import org.gradle.build.event.BuildEventsListenerRegistry
 import org.gradle.api.Plugin
@@ -31,6 +32,9 @@ public class BuildMetricsPlugin @Inject constructor(
             serviceSpec.parameters.rootDirectory.set(target.rootDir)
             serviceSpec.parameters.requestedTasks.set(target.gradle.startParameter.taskNames)
             serviceSpec.parameters.timeoutMillis.set(HTTP_TIMEOUT_MILLIS)
+            serviceSpec.parameters.bufferDirectory.set(
+                File(target.gradle.gradleUserHomeDir, BUFFER_DIRECTORY),
+            )
         }
 
         listenerRegistry.onTaskCompletion(service)
@@ -49,5 +53,6 @@ public class BuildMetricsPlugin @Inject constructor(
         const val ENDPOINT_ENVIRONMENT_VARIABLE = "BUILD_METRICS_ES_ENDPOINT"
         const val DEFAULT_ENDPOINT = "http://compilation-metrics/gradle"
         const val HTTP_TIMEOUT_MILLIS = 2_000
+        const val BUFFER_DIRECTORY = "kotlin-local-metrics/unsent-build-metrics"
     }
 }

gradle-build-metrics-plugin/src/main/kotlin/io/agodadev/localmetrics/gradle/BuildMetricsService.kt

@@ -25,6 +25,9 @@ public abstract class BuildMetricsService :
         public val rootDirectory: DirectoryProperty
         public val requestedTasks: ListProperty<String>
         public val timeoutMillis: Property<Int>
+
+        /** Where payloads are parked while the metrics endpoint is unreachable. */
+        public val bufferDirectory: DirectoryProperty
     }
 
     private val taskMetrics = ConcurrentHashMap<String, TaskMetric>()
@@ -74,8 +77,10 @@ public abstract class BuildMetricsService :
 
             MetricsPublisher.post(
                 endpoint = parameters.endpoint.get(),
+                payloadId = payload.id,
                 json = BuildMetricsJson.encode(payload),
                 timeoutMillis = parameters.timeoutMillis.get(),
+                buffer = parameters.bufferDirectory.orNull?.asFile?.let(::UnsentMetricsBuffer),
             )
         }
     }

gradle-build-metrics-plugin/src/main/kotlin/io/agodadev/localmetrics/gradle/MetricsPublisher.kt

@@ -1,12 +1,15 @@
 package io.agodadev.localmetrics.gradle
 
+import java.io.IOException
 import java.net.URI
 import java.net.http.HttpClient
 import java.net.http.HttpRequest
 import java.net.http.HttpResponse
 import java.time.Duration
+import java.util.concurrent.CompletableFuture
 import java.util.concurrent.Executors
 import java.util.concurrent.TimeUnit
+import java.util.concurrent.TimeoutException
 
 internal object MetricsPublisher {
     private val executor = Executors.newCachedThreadPool { runnable ->
@@ -20,17 +23,117 @@ internal object MetricsPublisher {
         .executor(executor)
         .build()
 
-    fun post(endpoint: String, json: String, timeoutMillis: Int) {
-        runCatching {
-            val request = HttpRequest.newBuilder(URI.create(endpoint))
-                .timeout(Duration.ofMillis(timeoutMillis.toLong()))
-                .header("Content-Type", "application/json")
-                .POST(HttpRequest.BodyPublishers.ofString(json))
-                .build()
-
-            client.sendAsync(request, HttpResponse.BodyHandlers.discarding())
-                .orTimeout(timeoutMillis.toLong(), TimeUnit.MILLISECONDS)
-                .exceptionally { null }
+    /**
+     * Sends [json] and, when [buffer] is present, either buffers it for a later build (the
+     * endpoint was unreachable) or flushes previously buffered payloads (the send succeeded).
+     *
+     * Returns immediately: the returned future exists for tests, callers on the build's
+     * critical path must not wait on it.
+     */
+    fun post(
+        endpoint: String,
+        payloadId: String,
+        json: String,
+        timeoutMillis: Int,
+        buffer: UnsentMetricsBuffer? = null,
+    ): CompletableFuture<Unit> = runCatching {
+        send(endpoint, json, timeoutMillis).thenCompose { outcome ->
+            when (outcome) {
+                SendOutcome.SUCCEEDED -> flush(endpoint, timeoutMillis, buffer)
+                SendOutcome.UNREACHABLE -> {
+                    buffer?.save(payloadId, json)
+                    completed()
+                }
+                SendOutcome.REJECTED -> completed()
+            }
         }
+    }.getOrElse { completed() }
+
+    private fun send(
+        endpoint: String,
+        json: String,
+        timeoutMillis: Int,
+    ): CompletableFuture<SendOutcome> {
+        val request = HttpRequest.newBuilder(URI.create(endpoint))
+            .timeout(Duration.ofMillis(timeoutMillis.toLong()))
+            .header("Content-Type", "application/json")
+            .POST(HttpRequest.BodyPublishers.ofString(json))
+            .build()
+
+        return client.sendAsync(request, HttpResponse.BodyHandlers.discarding())
+            .orTimeout(timeoutMillis.toLong(), TimeUnit.MILLISECONDS)
+            .handle { response, failure ->
+                when {
+                    failure != null -> if (failure.isConnectivityFailure()) {
+                        SendOutcome.UNREACHABLE
+                    } else {
+                        SendOutcome.REJECTED
+                    }
+                    response.statusCode() in 200..299 -> SendOutcome.SUCCEEDED
+                    else -> SendOutcome.REJECTED
+                }
+            }
+    }
+
+    /**
+     * Drains the buffer one payload at a time, stopping as soon as the endpoint goes
+     * unreachable again so a flaky connection cannot turn into a burst of doomed requests.
+     */
+    private fun flush(
+        endpoint: String,
+        timeoutMillis: Int,
+        buffer: UnsentMetricsBuffer?,
+    ): CompletableFuture<Unit> {
+        if (buffer == null) {
+            return completed()
+        }
+
+        return buffer.list()
+            .fold(CompletableFuture.completedFuture(true)) { chain, entry ->
+                chain.thenCompose { reachable ->
+                    val json = if (reachable) buffer.read(entry) else null
+                    when {
+                        !reachable -> CompletableFuture.completedFuture(false)
+                        // An unreadable entry can never be sent; drop it rather than retry forever.
+                        json == null -> {
+                            buffer.delete(entry)
+                            CompletableFuture.completedFuture(true)
+                        }
+                        else -> send(endpoint, json, timeoutMillis).thenApply { outcome ->
+                            if (outcome != SendOutcome.UNREACHABLE) {
+                                // Sent, or refused by a reachable endpoint — either way it is done.
+                                buffer.delete(entry)
+                            }
+                            outcome != SendOutcome.UNREACHABLE
+                        }
+                    }
+                }
+            }
+            .thenApply { }
+    }
+
+    private fun completed(): CompletableFuture<Unit> = CompletableFuture.completedFuture(Unit)
+
+    private fun Throwable.isConnectivityFailure(): Boolean {
+        var failure: Throwable? = this
+        val seen = mutableSetOf<Throwable>()
+        while (failure != null && seen.add(failure)) {
+            if (failure is IOException || failure is TimeoutException) {
+                return true
+            }
+            failure = failure.cause
+        }
+        return false
+    }
+
+    private enum class SendOutcome {
+        /** The endpoint accepted the payload. */
+        SUCCEEDED,
+
+        /** The endpoint could not be reached; the payload is worth retrying later. */
+        UNREACHABLE,
+
+        /** The endpoint was reached but did not accept the payload; retrying will not help. */
+        REJECTED,
     }
 }

gradle-build-metrics-plugin/src/main/kotlin/io/agodadev/localmetrics/gradle/UnsentMetricsBuffer.kt

@@ -0,0 +1,71 @@
+package io.agodadev.localmetrics.gradle
+
+import java.io.File
+
+/**
+ * A bounded, best-effort store-and-forward buffer for payloads that could not be sent.
+ *
+ * One file per payload, named by the payload id. Every operation swallows its errors: a
+ * developer's build must never fail because a metrics file could not be written or read.
+ */
+internal class UnsentMetricsBuffer(
+    private val directory: File,
+    private val maxEntries: Int = DEFAULT_MAX_ENTRIES,
+    private val maxAgeMillis: Long = DEFAULT_MAX_AGE_MILLIS,
+) {
+    fun save(id: String, json: String) {
+        runCatching {
+            directory.mkdirs()
+            val entry = File(directory, "${fileName(id)}$EXTENSION")
+            val temporary = File(directory, "${entry.name}$TEMPORARY_EXTENSION")
+            temporary.writeText(json)
+            if (!temporary.renameTo(entry)) {
+                temporary.copyTo(entry, overwrite = true)
+                temporary.delete()
+            }
+            prune()
+        }
+    }
+
+    /** Buffered entries, oldest first, so a flush drains them in the order they failed. */
+    fun list(): List<File> = runCatching {
+        directory.listFiles { file -> file.isFile && file.name.endsWith(EXTENSION) }
+            .orEmpty()
+            .sortedBy(File::lastModified)
+    }.getOrDefault(emptyList())
+
+    fun read(entry: File): String? = runCatching { entry.readText() }.getOrNull()
+
+    fun delete(entry: File) {
+        runCatching { entry.delete() }
+    }
+
+    /** Drops entries older than [maxAgeMillis], then the oldest entries beyond [maxEntries]. */
+    fun prune(nowMillis: Long = System.currentTimeMillis()) {
+        runCatching {
+            val expiredBefore = nowMillis - maxAgeMillis
+            val (expired, current) = list().partition { it.lastModified() < expiredBefore }
+            expired.forEach(::delete)
+            current.dropLast(maxEntries.coerceAtLeast(0)).forEach(::delete)
+        }
+    }
+
+    private fun fileName(id: String): String {
+        val sanitized = id
+            .take(MAX_FILE_NAME_LENGTH)
+            .map { character ->
+                if (character.isLetterOrDigit() || character == '-' || character == '_') character else '_'
+            }
+            .joinToString(separator = "")
+
+        return sanitized.ifBlank { "payload" }
+    }
+
+    private companion object {
+        const val EXTENSION = ".json"
+        const val TEMPORARY_EXTENSION = ".tmp"
+        const val MAX_FILE_NAME_LENGTH = 64
+        const val DEFAULT_MAX_ENTRIES = 200
+        const val DEFAULT_MAX_AGE_MILLIS = 7L * 24 * 60 * 60 * 1_000
+    }
+}