@capgo/capacitor-updater 8.51.4 → 8.51.6

package/android/src/main/java/ee/forgr/capacitor_updater/CapgoUpdater.java

@@ -54,6 +54,7 @@ import java.util.concurrent.Executors;
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.ScheduledFuture;
 import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.zip.ZipEntry;
 import java.util.zip.ZipInputStream;
 import okhttp3.*;
@@ -91,6 +92,7 @@ public class CapgoUpdater {
     public SharedPreferences prefs;
 
     public File documentsDir;
+    public File noBackupDir;
     public Boolean directUpdate = false;
     public Activity activity;
     public String pluginVersion = "";
@@ -112,17 +114,31 @@ public class CapgoUpdater {
     // Cached key ID calculated once from publicKey
     private String cachedKeyId = "";
 
-    // Flag to track if we received a 429 response - stops requests until app restart
-    private static volatile boolean rateLimitExceeded = false;
+    // Temporary 429 block until this epoch ms (Retry-After / rateLimitResetAt). No sticky latch.
+    // Guarded by rateLimitStateLock so concurrent 429s cannot shorten the window or mix metadata.
+    private static final Object rateLimitStateLock = new Object();
+    private static long rateLimitBlockedUntilMs = 0L;
+    private static String rateLimitBlockedError = "too_many_requests";
+    private static String rateLimitBlockedMessage = "Too many requests";
 
-    // Flag to track if we've already sent the rate limit statistic - prevents infinite loop
-    private static volatile boolean rateLimitStatisticSent = false;
+    // Flag to track if we've already sent the rate limit statistic - prevents infinite loop.
+    // Released again when the send fails, so a later 429 can retry it.
+    private static boolean rateLimitStatisticSent = false;
+
+    // Upper bound for a client-side 429 block, so a bogus Retry-After cannot block the app for days.
+    private static final long MAX_RATE_LIMIT_WINDOW_MS = 24 * 60 * 60 * 1000L;
 
     // Stats batching - queue events and send max once per second
     private final List<QueuedStatsEvent> statsQueue = new CopyOnWriteArrayList<>();
+    private final List<QueuedStatsEvent> statsInFlight = new ArrayList<>();
+    private final Object pendingStatsPersistLock = new Object();
     private final ScheduledExecutorService statsScheduler = Executors.newSingleThreadScheduledExecutor();
     private ScheduledFuture<?> statsFlushTask = null;
+    private final AtomicBoolean statsFlushInFlight = new AtomicBoolean(false);
+    private final AtomicBoolean statsStopped = new AtomicBoolean(false);
     private static final long STATS_FLUSH_INTERVAL_MS = 1000;
+    private static final String PENDING_STATS_FILE = "capgo_pending_stats.json";
+    private static final int MAX_PENDING_STATS = 200;
 
     private static final class QueuedStatsEvent {
 
@@ -386,7 +402,7 @@ public class CapgoUpdater {
         io.execute(() -> cacheBundleFiles(id));
     }
 
-    private void cacheBundleFiles(final String id) {
+    void cacheBundleFiles(final String id) {
         if (this.activity == null) {
             logger.debug("Skip delta cache population: activity is null");
             return;
@@ -408,13 +424,25 @@ public class CapgoUpdater {
             return;
         }
 
+        final File builtinFolder = new File(this.activity.getFilesDir(), "public");
+
         final List<File> files = new ArrayList<>();
         collectFiles(bundleDir, files);
+        final int bundlePrefixLength = bundleDir.getAbsolutePath().length() + 1;
         for (File file : files) {
             final String checksum = CryptoCipher.calcChecksum(file);
             if (checksum.isEmpty()) {
                 continue;
             }
+
+            // Builtin is already a permanent reuse source (see isManifestEntryAvailableLocally),
+            // so there's no need to also duplicate a byte-identical file into the delta cache.
+            final String relativePath = file.getAbsolutePath().substring(bundlePrefixLength);
+            final File builtinFile = new File(builtinFolder, relativePath);
+            if (verifyChecksum(builtinFile, checksum)) {
+                continue;
+            }
+
             final String cacheName = checksum + "_" + file.getName();
             final File cacheFile = new File(cacheDir, cacheName);
             if (cacheFile.exists()) {
@@ -1913,30 +1941,185 @@ public class CapgoUpdater {
         return json;
     }
 
+    private static final class RemoteBlockResult {
+
+        final boolean blocked;
+        final String error;
+        final String message;
+
+        RemoteBlockResult(final boolean blocked, final String error, final String message) {
+            this.blocked = blocked;
+            this.error = error;
+            this.message = message;
+        }
+    }
+
+    /**
+     * Handle HTTP 429 responses by honouring Retry-After / rateLimitResetAt.
+     * All 429s use the same temporary client block — no sticky latch until restart.
+     */
+    private RemoteBlockResult checkAndHandleRateLimitResponse(Response response, String responseData) {
+        if (response == null || response.code() != 429) {
+            return new RemoteBlockResult(false, "", "");
+        }
+
+        final String parsedError = parseRemoteError(responseData);
+        final String parsedMessage = parseRemoteMessage(responseData);
+        final String errorCode = parsedError.isEmpty() ? "too_many_requests" : parsedError;
+        final String message = parsedMessage.isEmpty() ? "Too many requests" : parsedMessage;
+
+        final long retryUntilMs = resolveRateLimitBlockedUntilMs(response, responseData);
+        synchronized (rateLimitStateLock) {
+            if (retryUntilMs > rateLimitBlockedUntilMs) {
+                rateLimitBlockedUntilMs = retryUntilMs;
+                rateLimitBlockedError = errorCode;
+                rateLimitBlockedMessage = message;
+            } else if (rateLimitBlockedUntilMs <= 0L) {
+                rateLimitBlockedError = errorCode;
+                rateLimitBlockedMessage = message;
+            }
+        }
+
+        // Claim last, and only when there is somewhere to send it, so a 429 burst with no
+        // stats URL does not claim and release the latch once per response.
+        if ("too_many_requests".equals(errorCode) && !this.previewSession && this.hasStatsUrl() && claimRateLimitStatistic()) {
+            sendRateLimitStatistic();
+        }
+
+        final long nowMs = System.currentTimeMillis();
+        final long retryAfter = Math.max(0L, (Math.max(retryUntilMs, nowMs) - nowMs + 999L) / 1000L);
+        logger.warn("Received 429 (" + errorCode + "). Honouring Retry-After: " + retryAfter + "s.");
+        return new RemoteBlockResult(true, errorCode, message);
+    }
+
+    private String parseRemoteError(final String responseData) {
+        if (responseData == null || responseData.isEmpty()) {
+            return "";
+        }
+        try {
+            final JSONObject json = new JSONObject(responseData);
+            return json.optString("error", "");
+        } catch (JSONException ignored) {
+            return "";
+        }
+    }
+
+    private String parseRemoteMessage(final String responseData) {
+        if (responseData == null || responseData.isEmpty()) {
+            return "";
+        }
+        try {
+            final JSONObject json = new JSONObject(responseData);
+            return json.optString("message", "");
+        } catch (JSONException ignored) {
+            return "";
+        }
+    }
+
+    private long resolveRateLimitBlockedUntilMs(final Response response, final String responseData) {
+        final long nowMs = System.currentTimeMillis();
+        final double candidate = rawRateLimitDeadlineMs(response, responseData, nowMs);
+        // NaN and past deadlines mean "no client-side block"; anything further out is capped.
+        if (!(candidate > nowMs)) {
+            return 0L;
+        }
+        return (long) Math.min(candidate, (double) nowMs + MAX_RATE_LIMIT_WINDOW_MS);
+    }
+
+    private double rawRateLimitDeadlineMs(final Response response, final String responseData, final long nowMs) {
+        final String header = response.header("Retry-After");
+        if (header != null) {
+            try {
+                final double seconds = Double.parseDouble(header.trim());
+                if (seconds >= 0) {
+                    return nowMs + seconds * 1000d;
+                }
+            } catch (NumberFormatException ignored) {
+                // Fall through to body fields
+            }
+        }
+
+        if (responseData != null && !responseData.isEmpty()) {
+            try {
+                final JSONObject json = new JSONObject(responseData);
+                final JSONObject moreInfo = json.optJSONObject("moreInfo");
+                if (moreInfo != null && moreInfo.has("retryAfterSeconds")) {
+                    final double retryAfter = moreInfo.getDouble("retryAfterSeconds");
+                    if (retryAfter >= 0) {
+                        return nowMs + retryAfter * 1000d;
+                    }
+                } else if (json.has("retryAfterSeconds")) {
+                    final double retryAfter = json.getDouble("retryAfterSeconds");
+                    if (retryAfter >= 0) {
+                        return nowMs + retryAfter * 1000d;
+                    }
+                }
+                if (moreInfo != null && moreInfo.has("rateLimitResetAt")) {
+                    return moreInfo.getDouble("rateLimitResetAt");
+                } else if (json.has("rateLimitResetAt")) {
+                    return json.getDouble("rateLimitResetAt");
+                }
+            } catch (JSONException ignored) {
+                // No retry hint
+            }
+        }
+
+        // No retry hint — do not hold a client-side block; allow immediate retry to the worker
+        return 0d;
+    }
+
+    private static boolean claimRateLimitStatistic() {
+        synchronized (rateLimitStateLock) {
+            if (rateLimitStatisticSent) {
+                return false;
+            }
+            rateLimitStatisticSent = true;
+            return true;
+        }
+    }
+
     /**
-     * Check if a 429 (Too Many Requests) response was received and set the flag
+     * Give the claim back when the statistic never made it out, so a later 429 can retry it.
      */
-    private boolean checkAndHandleRateLimitResponse(Response response) {
-        if (response.code() == 429) {
-            // Send a statistic about the rate limit BEFORE setting the flag
-            // Only send once to prevent infinite loop if the stat request itself gets rate limited
-            if (!this.previewSession && !rateLimitExceeded && !rateLimitStatisticSent) {
-                rateLimitStatisticSent = true;
-                sendRateLimitStatistic();
-            }
-            rateLimitExceeded = true;
-            logger.warn("Rate limit exceeded (429). Stopping all stats and channel requests until app restart.");
+    private static void releaseRateLimitStatisticClaim() {
+        synchronized (rateLimitStateLock) {
+            rateLimitStatisticSent = false;
+        }
+    }
+
+    private boolean hasStatsUrl() {
+        final String url = this.statsUrl;
+        return url != null && !url.isEmpty();
+    }
+
+    private boolean isRemoteBlocked() {
+        synchronized (rateLimitStateLock) {
+            if (rateLimitBlockedUntilMs <= 0L) {
+                return false;
+            }
+            if (System.currentTimeMillis() >= rateLimitBlockedUntilMs) {
+                rateLimitBlockedUntilMs = 0L;
+                return false;
+            }
             return true;
         }
-        return false;
+    }
+
+    private RemoteBlockResult remoteBlockedClientError() {
+        synchronized (rateLimitStateLock) {
+            return new RemoteBlockResult(true, rateLimitBlockedError, rateLimitBlockedMessage);
+        }
     }
 
     /**
-     * Send a synchronous statistic about rate limiting
+     * Send a statistic about rate limiting.
+     * Dispatched through OkHttp so no caller thread waits on the request.
      */
     private void sendRateLimitStatistic() {
         String statsUrl = this.statsUrl;
         if (statsUrl == null || statsUrl.isEmpty()) {
+            // The URL was cleared after the claim was taken; nothing went out, so hand it back.
+            releaseRateLimitStatisticClaim();
             return;
         }
 
@@ -1952,17 +2135,33 @@ public class CapgoUpdater {
                 .post(RequestBody.create(json.toString(), MediaType.get("application/json")))
                 .build();
 
-            // Send synchronously to ensure it goes out before the flag is set
             // User-Agent header is automatically added by DownloadService.sharedClient interceptor
-            try (Response response = DownloadService.sharedClient.newCall(request).execute()) {
-                if (response.isSuccessful()) {
-                    logger.info("Rate limit statistic sent");
-                } else {
-                    logger.error("Error sending rate limit statistic");
-                    logger.debug("Response code: " + response.code());
+            DownloadService.sharedClient.newCall(request).enqueue(
+                new okhttp3.Callback() {
+                    @Override
+                    public void onFailure(@NonNull Call call, @NonNull IOException e) {
+                        releaseRateLimitStatisticClaim();
+                        logger.error("Failed to send rate limit statistic");
+                        logger.debug("Error: " + e.getMessage());
+                    }
+
+                    @Override
+                    public void onResponse(@NonNull Call call, @NonNull Response response) {
+                        // The body is unused here; closing the Response closes it.
+                        try (response) {
+                            if (response.isSuccessful()) {
+                                logger.info("Rate limit statistic sent");
+                            } else {
+                                releaseRateLimitStatisticClaim();
+                                logger.error("Error sending rate limit statistic");
+                                logger.debug("Response code: " + response.code());
+                            }
+                        }
+                    }
                 }
-            }
+            );
         } catch (final Exception e) {
+            releaseRateLimitStatisticClaim();
             logger.error("Failed to send rate limit statistic");
             logger.debug("Error: " + e.getMessage());
         }
@@ -2001,7 +2200,27 @@ public class CapgoUpdater {
 
                         if (jsonResponse != null && (jsonResponse.has("error") || jsonResponse.has("kind"))) {
                             if (statusCode == 429) {
-                                checkAndHandleRateLimitResponse(response);
+                                final RemoteBlockResult rateLimit = checkAndHandleRateLimitResponse(response, responseData);
+                                Map<String, Object> retError = new HashMap<>();
+                                retError.put(
+                                    "error",
+                                    rateLimit.error.isEmpty() ? jsonResponse.optString("error", "too_many_requests") : rateLimit.error
+                                );
+                                retError.put(
+                                    "message",
+                                    rateLimit.message.isEmpty() ? jsonResponse.optString("message", "Too many requests") : rateLimit.message
+                                );
+                                if (jsonResponse.has("kind") && !jsonResponse.isNull("kind")) {
+                                    retError.put("kind", jsonResponse.getString("kind"));
+                                } else {
+                                    retError.put("kind", "failed");
+                                }
+                                if (jsonResponse.has("version") && !jsonResponse.isNull("version")) {
+                                    retError.put("version", jsonResponse.getString("version"));
+                                }
+                                retError.put("statusCode", statusCode);
+                                callback.callback(retError);
+                                return;
                             }
                             Map<String, Object> retError = new HashMap<>();
                             if (jsonResponse.has("error") && !jsonResponse.isNull("error")) {
@@ -2023,11 +2242,12 @@ public class CapgoUpdater {
                             return;
                         }
 
-                        // Check for 429 rate limit
-                        if (checkAndHandleRateLimitResponse(response)) {
+                        // Check for 429 rate limit without JSON body
+                        final RemoteBlockResult rateLimit = checkAndHandleRateLimitResponse(response, responseData);
+                        if (rateLimit.blocked) {
                             Map<String, Object> retError = new HashMap<>();
-                            retError.put("message", "Rate limit exceeded");
-                            retError.put("error", "rate_limit_exceeded");
+                            retError.put("message", rateLimit.message);
+                            retError.put("error", rateLimit.error);
                             retError.put("kind", "failed");
                             retError.put("statusCode", statusCode);
                             callback.callback(retError);
@@ -2080,6 +2300,16 @@ public class CapgoUpdater {
     }
 
     public void getLatest(final String updateUrl, final String channel, final String appIdOverride, final Callback callback) {
+        if (isRemoteBlocked()) {
+            final RemoteBlockResult blocked = remoteBlockedClientError();
+            logger.debug("Skipping getLatest due to remote block (" + blocked.error + ").");
+            final Map<String, Object> retError = new HashMap<>();
+            retError.put("message", blocked.message);
+            retError.put("error", blocked.error);
+            retError.put("kind", "failed");
+            callback.callback(retError);
+            return;
+        }
         JSONObject json;
         try {
             json = this.createInfoObject(appIdOverride);
@@ -2149,12 +2379,12 @@ public class CapgoUpdater {
             return;
         }
 
-        // Check if rate limit was exceeded
-        if (rateLimitExceeded) {
-            logger.debug("Skipping setChannel due to rate limit (429). Requests will resume after app restart.");
+        if (isRemoteBlocked()) {
+            final RemoteBlockResult blocked = remoteBlockedClientError();
+            logger.debug("Skipping setChannel due to remote block (" + blocked.error + ").");
             final Map<String, Object> retError = new HashMap<>();
-            retError.put("message", "Rate limit exceeded");
-            retError.put("error", "rate_limit_exceeded");
+            retError.put("message", blocked.message);
+            retError.put("error", blocked.error);
             callback.callback(retError);
             return;
         }
@@ -2208,12 +2438,12 @@ public class CapgoUpdater {
     }
 
     public void getChannel(final Callback callback, final SharedPreferences.Editor editor, final String defaultChannelKey) {
-        // Check if rate limit was exceeded
-        if (rateLimitExceeded) {
-            logger.debug("Skipping getChannel due to rate limit (429). Requests will resume after app restart.");
+        if (isRemoteBlocked()) {
+            final RemoteBlockResult blocked = remoteBlockedClientError();
+            logger.debug("Skipping getChannel due to remote block (" + blocked.error + ").");
             final Map<String, Object> retError = new HashMap<>();
-            retError.put("message", "Rate limit exceeded");
-            retError.put("error", "rate_limit_exceeded");
+            retError.put("message", blocked.message);
+            retError.put("error", blocked.error);
             callback.callback(retError);
             return;
         }
@@ -2258,25 +2488,18 @@ public class CapgoUpdater {
                 @Override
                 public void onResponse(@NonNull Call call, @NonNull Response response) throws IOException {
                     try (ResponseBody responseBody = response.body()) {
-                        // Check for 429 rate limit
-                        if (checkAndHandleRateLimitResponse(response)) {
+                        final String responseData = responseBody != null ? responseBody.string() : "";
+                        final RemoteBlockResult rateLimit = checkAndHandleRateLimitResponse(response, responseData);
+                        if (rateLimit.blocked) {
                             Map<String, Object> retError = new HashMap<>();
-                            retError.put("message", "Rate limit exceeded");
-                            retError.put("error", "rate_limit_exceeded");
+                            retError.put("message", rateLimit.message);
+                            retError.put("error", rateLimit.error);
                             callback.callback(retError);
                             return;
                         }
 
                         if (response.code() == 400) {
-                            if (responseBody == null) {
-                                Map<String, Object> retError = new HashMap<>();
-                                retError.put("message", "Empty response body");
-                                retError.put("error", "no_response_body");
-                                callback.callback(retError);
-                                return;
-                            }
-                            String data = responseBody.string();
-                            if (data.contains("channel_not_found") && !defaultChannel.isEmpty()) {
+                            if (responseData.contains("channel_not_found") && !defaultChannel.isEmpty()) {
                                 Map<String, Object> ret = new HashMap<>();
                                 ret.put("channel", defaultChannel);
                                 ret.put("status", "default");
@@ -2294,14 +2517,13 @@ public class CapgoUpdater {
                             return;
                         }
 
-                        if (responseBody == null) {
+                        if (responseData.isEmpty()) {
                             Map<String, Object> retError = new HashMap<>();
                             retError.put("message", "Empty response body");
                             retError.put("error", "no_response_body");
                             callback.callback(retError);
                             return;
                         }
-                        String responseData = responseBody.string();
                         JSONObject jsonResponse = new JSONObject(responseData);
 
                         // Check for server-side errors first
@@ -2359,12 +2581,12 @@ public class CapgoUpdater {
     }
 
     public void listChannels(final Callback callback) {
-        // Check if rate limit was exceeded
-        if (rateLimitExceeded) {
-            logger.debug("Skipping listChannels due to rate limit (429). Requests will resume after app restart.");
+        if (isRemoteBlocked()) {
+            final RemoteBlockResult blocked = remoteBlockedClientError();
+            logger.debug("Skipping listChannels due to remote block (" + blocked.error + ").");
             final Map<String, Object> retError = new HashMap<>();
-            retError.put("message", "Rate limit exceeded");
-            retError.put("error", "rate_limit_exceeded");
+            retError.put("message", blocked.message);
+            retError.put("error", blocked.error);
             callback.callback(retError);
             return;
         }
@@ -2423,11 +2645,12 @@ public class CapgoUpdater {
                 @Override
                 public void onResponse(@NonNull Call call, @NonNull Response response) throws IOException {
                     try (ResponseBody responseBody = response.body()) {
-                        // Check for 429 rate limit
-                        if (checkAndHandleRateLimitResponse(response)) {
+                        final String data = responseBody != null ? responseBody.string() : "";
+                        final RemoteBlockResult rateLimit = checkAndHandleRateLimitResponse(response, data);
+                        if (rateLimit.blocked) {
                             Map<String, Object> retError = new HashMap<>();
-                            retError.put("message", "Rate limit exceeded");
-                            retError.put("error", "rate_limit_exceeded");
+                            retError.put("message", rateLimit.message);
+                            retError.put("error", rateLimit.error);
                             callback.callback(retError);
                             return;
                         }
@@ -2440,14 +2663,13 @@ public class CapgoUpdater {
                             return;
                         }
 
-                        if (responseBody == null) {
+                        if (data.isEmpty()) {
                             Map<String, Object> retError = new HashMap<>();
                             retError.put("message", "Empty response body");
                             retError.put("error", "no_response_body");
                             callback.callback(retError);
                             return;
                         }
-                        String data = responseBody.string();
 
                         try {
                             Map<String, Object> ret = parseListChannelsResponse(data);
@@ -2535,6 +2757,10 @@ public class CapgoUpdater {
         final Map<String, String> metadata,
         final Runnable onSent
     ) {
+        if (statsStopped.get()) {
+            return;
+        }
+
         if (this.previewSession) {
             if (logger != null) {
                 logger.debug("Skipping sendStats during preview session.");
@@ -2542,12 +2768,6 @@ public class CapgoUpdater {
             return;
         }
 
-        // Check if rate limit was exceeded
-        if (rateLimitExceeded) {
-            logger.debug("Skipping sendStats due to rate limit (429). Stats will resume after app restart.");
-            return;
-        }
-
         String statsUrl = this.statsUrl;
         if (statsUrl == null || statsUrl.isEmpty()) {
             return;
@@ -2564,16 +2784,150 @@ public class CapgoUpdater {
                 json.put("metadata", new JSONObject(metadata));
             }
         } catch (JSONException e) {
-            logger.error("Error preparing stats");
-            logger.debug("JSONException: " + e.getMessage());
+            if (logger != null) {
+                logger.error("Error preparing stats");
+                logger.debug("JSONException: " + e.getMessage());
+            }
             return;
         }
 
-        statsQueue.add(new QueuedStatsEvent(json, onSent));
+        synchronized (statsQueue) {
+            if (statsStopped.get()) {
+                return;
+            }
+            while (statsQueue.size() >= MAX_PENDING_STATS) {
+                statsQueue.remove(0);
+            }
+            statsQueue.add(new QueuedStatsEvent(json, onSent));
+        }
         ensureStatsTimerStarted();
     }
 
+    public void restorePendingStats() {
+        File file = pendingStatsFile();
+        if (file == null || !file.exists()) {
+            return;
+        }
+        try {
+            String raw = readFileUtf8(file);
+            JSONArray arr = new JSONArray(raw);
+            synchronized (statsQueue) {
+                for (int i = 0; i < arr.length(); i++) {
+                    if (statsQueue.size() >= MAX_PENDING_STATS) {
+                        break;
+                    }
+                    statsQueue.add(new QueuedStatsEvent(arr.getJSONObject(i), null));
+                }
+            }
+            if (!statsQueue.isEmpty()) {
+                if (logger != null) {
+                    logger.info("Restored " + statsQueue.size() + " pending stats events");
+                }
+                ensureStatsTimerStarted();
+            }
+        } catch (Exception e) {
+            if (logger != null) {
+                logger.error("Failed to restore pending stats");
+                logger.debug("Error: " + e.getMessage());
+            }
+        }
+    }
+
+    int pendingStatsCount() {
+        return statsQueue.size();
+    }
+
+    public void persistPendingStats() {
+        persistStatsQueue();
+    }
+
+    private File pendingStatsFile() {
+        final File dir = this.noBackupDir != null ? this.noBackupDir : this.documentsDir;
+        if (dir == null) {
+            return null;
+        }
+        return new File(dir, PENDING_STATS_FILE);
+    }
+
+    private void persistStatsQueue() {
+        persistStatsQueue(false);
+    }
+
+    private void persistStatsQueue(final boolean force) {
+        File file = pendingStatsFile();
+        if (file == null) {
+            return;
+        }
+        synchronized (pendingStatsPersistLock) {
+            if (statsStopped.get() && !force) {
+                return;
+            }
+            JSONArray arr = new JSONArray();
+            synchronized (statsQueue) {
+                final List<QueuedStatsEvent> combined = new ArrayList<>(statsInFlight.size() + statsQueue.size());
+                combined.addAll(statsInFlight);
+                combined.addAll(statsQueue);
+                final int start = Math.max(0, combined.size() - MAX_PENDING_STATS);
+                for (int i = start; i < combined.size(); i++) {
+                    arr.put(combined.get(i).event);
+                }
+            }
+            try {
+                if (arr.length() == 0) {
+                    if (file.exists() && !file.delete()) {
+                        if (logger != null) {
+                            logger.error("Failed to delete empty stats queue file");
+                        }
+                    }
+                    return;
+                }
+                writeFileAtomically(file, arr.toString().getBytes(StandardCharsets.UTF_8));
+            } catch (Exception e) {
+                if (logger != null) {
+                    logger.error("Failed to persist stats queue");
+                    logger.debug("Error: " + e.getMessage());
+                }
+            }
+        }
+    }
+
+    private static String readFileUtf8(final File file) throws IOException {
+        final long length = file.length();
+        final byte[] buf = new byte[length > Integer.MAX_VALUE ? Integer.MAX_VALUE : (int) length];
+        try (FileInputStream in = new FileInputStream(file)) {
+            int offset = 0;
+            while (offset < buf.length) {
+                final int read = in.read(buf, offset, buf.length - offset);
+                if (read < 0) {
+                    break;
+                }
+                offset += read;
+            }
+            return new String(buf, 0, offset, StandardCharsets.UTF_8);
+        }
+    }
+
+    private static void writeFileAtomically(final File file, final byte[] bytes) throws IOException {
+        final File tmp = new File(file.getAbsolutePath() + ".tmp");
+        try (FileOutputStream out = new FileOutputStream(tmp)) {
+            out.write(bytes);
+            out.flush();
+        }
+        if (tmp.renameTo(file)) {
+            return;
+        }
+        if (file.exists() && !file.delete()) {
+            throw new IOException("Failed to replace " + file.getAbsolutePath());
+        }
+        if (!tmp.renameTo(file)) {
+            throw new IOException("Failed to persist " + file.getAbsolutePath());
+        }
+    }
+
     private synchronized void ensureStatsTimerStarted() {
+        if (statsStopped.get()) {
+            return;
+        }
         if (statsFlushTask == null || statsFlushTask.isCancelled() || statsFlushTask.isDone()) {
             statsFlushTask = statsScheduler.scheduleAtFixedRate(
                 this::flushStatsQueue,
@@ -2585,25 +2939,45 @@ public class CapgoUpdater {
     }
 
     private void flushStatsQueue() {
+        if (statsStopped.get()) {
+            return;
+        }
         if (statsQueue.isEmpty()) {
             return;
         }
 
+        // While Retry-After is active, keep stats queued and skip the network call.
+        if (isRemoteBlocked()) {
+            logger.debug("Deferring stats flush until Retry-After expires.");
+            return;
+        }
+
         String statsUrl = this.statsUrl;
         if (statsUrl == null || statsUrl.isEmpty()) {
-            statsQueue.clear();
+            synchronized (statsQueue) {
+                statsQueue.clear();
+                statsInFlight.clear();
+            }
+            persistStatsQueue();
+            return;
+        }
+
+        if (!statsFlushInFlight.compareAndSet(false, true)) {
             return;
         }
 
-        // Copy and clear the queue atomically using synchronized block
-        List<QueuedStatsEvent> eventsToSend;
+        final List<QueuedStatsEvent> eventsToSend;
         synchronized (statsQueue) {
             if (statsQueue.isEmpty()) {
+                statsFlushInFlight.set(false);
                 return;
             }
             eventsToSend = new ArrayList<>(statsQueue);
             statsQueue.clear();
+            statsInFlight.clear();
+            statsInFlight.addAll(eventsToSend);
         }
+        persistStatsQueue();
 
         JSONArray jsonArray = new JSONArray();
         for (QueuedStatsEvent queuedEvent : eventsToSend) {
@@ -2620,32 +2994,93 @@ public class CapgoUpdater {
             new okhttp3.Callback() {
                 @Override
                 public void onFailure(@NonNull Call call, @NonNull IOException e) {
-                    logger.error("Failed to send stats batch");
-                    logger.debug("Error: " + e.getMessage());
+                    if (abandonStoppedStatsFlush()) {
+                        return;
+                    }
+                    requeueStatsEvents(eventsToSend);
+                    if (logger != null) {
+                        logger.error("Failed to send stats batch");
+                        logger.debug("Error: " + e.getMessage());
+                    }
+                    statsFlushInFlight.set(false);
                 }
 
                 @Override
                 public void onResponse(@NonNull Call call, @NonNull Response response) throws IOException {
                     try (ResponseBody responseBody = response.body()) {
-                        // Check for 429 rate limit
-                        if (checkAndHandleRateLimitResponse(response)) {
+                        if (abandonStoppedStatsFlush()) {
+                            return;
+                        }
+                        final String responseData = responseBody != null ? responseBody.string() : "";
+                        if (checkAndHandleRateLimitResponse(response, responseData).blocked) {
+                            requeueStatsEvents(eventsToSend);
                             return;
                         }
 
                         if (response.isSuccessful()) {
-                            logger.info("Stats batch sent successfully");
-                            logger.debug("Sent " + eventCount + " events");
+                            synchronized (statsQueue) {
+                                statsInFlight.clear();
+                            }
+                            persistStatsQueue();
+                            if (logger != null) {
+                                logger.info("Stats batch sent successfully");
+                                logger.debug("Sent " + eventCount + " events");
+                            }
                             runStatsCallbacks(eventsToSend);
+                        } else if (isTransientStatsFailure(response.code())) {
+                            requeueStatsEvents(eventsToSend);
+                            if (logger != null) {
+                                logger.error("Error sending stats batch");
+                                logger.debug("Retrying later, response code: " + response.code());
+                            }
                         } else {
-                            logger.error("Error sending stats batch");
-                            logger.debug("Response code: " + response.code());
+                            synchronized (statsQueue) {
+                                statsInFlight.clear();
+                            }
+                            persistStatsQueue();
+                            if (logger != null) {
+                                logger.error("Dropping stats batch after permanent error");
+                                logger.debug("Response code: " + response.code());
+                            }
                         }
+                    } finally {
+                        statsFlushInFlight.set(false);
                     }
                 }
             }
         );
     }
 
+    private boolean abandonStoppedStatsFlush() {
+        if (!statsStopped.get()) {
+            return false;
+        }
+        statsFlushInFlight.set(false);
+        return true;
+    }
+
+    /**
+     * Only 429, request timeout and 5xx are worth retrying; other 4xx are permanent rejections.
+     */
+    private static boolean isTransientStatsFailure(final int statusCode) {
+        return statusCode == 429 || statusCode == 408 || statusCode >= 500;
+    }
+
+    private void requeueStatsEvents(final List<QueuedStatsEvent> events) {
+        if (statsStopped.get() || events == null || events.isEmpty()) {
+            return;
+        }
+        synchronized (statsQueue) {
+            statsInFlight.clear();
+            statsQueue.addAll(0, events);
+            while (statsQueue.size() > MAX_PENDING_STATS) {
+                statsQueue.remove(0);
+            }
+        }
+        persistStatsQueue();
+        ensureStatsTimerStarted();
+    }
+
     private void runStatsCallbacks(final List<QueuedStatsEvent> sentEvents) {
         for (final QueuedStatsEvent sentEvent : sentEvents) {
             if (sentEvent.onSent == null) {
@@ -2833,14 +3268,15 @@ public class CapgoUpdater {
      * Should be called when the plugin is destroyed to prevent resource leaks.
      */
     public void shutdown() {
+        statsStopped.set(true);
         // Cancel the scheduled task
         if (statsFlushTask != null) {
             statsFlushTask.cancel(false);
             statsFlushTask = null;
         }
 
-        // Flush any remaining stats before shutdown
-        flushStatsQueue();
+        // Write once, then ignore later callbacks so they cannot delete a newer instance's file.
+        persistStatsQueue(true);
 
         // Shutdown the scheduler
         statsScheduler.shutdown();