@capgo/capacitor-updater 8.51.3 → 8.51.5

package/android/build.gradle

@@ -50,7 +50,7 @@ repositories {
 
 dependencies {
     def work_version = "2.10.5"
-    def lifecycle_version = "2.10.0"
+    def lifecycle_version = "2.11.0"
     implementation "androidx.work:work-runtime:$work_version"
     implementation "androidx.lifecycle:lifecycle-process:$lifecycle_version"
     implementation "com.google.android.gms:play-services-tasks:18.4.1"

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

@@ -146,7 +146,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
     static final int APPLICATION_EXIT_REASON_USER_REQUESTED = 10;
     static final int APPLICATION_EXIT_REASON_DEPENDENCY_DIED = 12;
 
-    private final String pluginVersion = "8.51.3";
+    private final String pluginVersion = "8.51.5";
     private static final String DELAY_CONDITION_PREFERENCES = "";
 
     private SharedPreferences.Editor editor;
@@ -3990,7 +3990,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
 
                 new AlertDialog.Builder(getActivity())
                     .setTitle("Preview started")
-                    .setMessage("Shake your device anytime to reload or leave the test app.")
+                    .setMessage("shake".equals(this.shakeMenuGesture) ? "Shake to open menu." : "Three-finger pinch to open menu.")
                     .setPositiveButton("Got it", (dialog, which) -> dialog.dismiss())
                     .show();
             } catch (final Exception e) {

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

@@ -112,11 +112,19 @@ 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<>();
@@ -386,7 +394,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 +416,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 +1933,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;
+        }
+    }
+
     /**
-     * Check if a 429 (Too Many Requests) response was received and set the flag
+     * Handle HTTP 429 responses by honouring Retry-After / rateLimitResetAt.
+     * All 429s use the same temporary client block — no sticky latch until restart.
      */
-    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 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;
         }
-        return false;
     }
 
     /**
-     * Send a synchronous statistic about rate limiting
+     * Give the claim back when the statistic never made it out, so a later 429 can retry it.
+     */
+    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;
+        }
+    }
+
+    private RemoteBlockResult remoteBlockedClientError() {
+        synchronized (rateLimitStateLock) {
+            return new RemoteBlockResult(true, rateLimitBlockedError, rateLimitBlockedMessage);
+        }
+    }
+
+    /**
+     * 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 +2127,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 +2192,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 +2234,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 +2292,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 +2371,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 +2430,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 +2480,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 +2509,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 +2573,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 +2637,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 +2655,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);
@@ -2542,12 +2756,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;
@@ -2569,7 +2777,10 @@ public class CapgoUpdater {
             return;
         }
 
-        statsQueue.add(new QueuedStatsEvent(json, onSent));
+        // Same lock as the flush transaction, so an event added mid-flush is never dropped.
+        synchronized (statsQueue) {
+            statsQueue.add(new QueuedStatsEvent(json, onSent));
+        }
         ensureStatsTimerStarted();
     }
 
@@ -2589,9 +2800,17 @@ public class CapgoUpdater {
             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();
+            }
             return;
         }
 
@@ -2620,6 +2839,8 @@ public class CapgoUpdater {
             new okhttp3.Callback() {
                 @Override
                 public void onFailure(@NonNull Call call, @NonNull IOException e) {
+                    // Keep events for a later flush attempt.
+                    requeueStatsEvents(eventsToSend);
                     logger.error("Failed to send stats batch");
                     logger.debug("Error: " + e.getMessage());
                 }
@@ -2627,8 +2848,9 @@ 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() : "";
+                        if (checkAndHandleRateLimitResponse(response, responseData).blocked) {
+                            requeueStatsEvents(eventsToSend);
                             return;
                         }
 
@@ -2636,8 +2858,13 @@ public class CapgoUpdater {
                             logger.info("Stats batch sent successfully");
                             logger.debug("Sent " + eventCount + " events");
                             runStatsCallbacks(eventsToSend);
-                        } else {
+                        } else if (isTransientStatsFailure(response.code())) {
+                            requeueStatsEvents(eventsToSend);
                             logger.error("Error sending stats batch");
+                            logger.debug("Retrying later, response code: " + response.code());
+                        } else {
+                            // Permanent rejection: retrying would loop forever and block the queue.
+                            logger.error("Dropping stats batch after permanent error");
                             logger.debug("Response code: " + response.code());
                         }
                     }
@@ -2646,6 +2873,23 @@ public class CapgoUpdater {
         );
     }
 
+    /**
+     * 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 (events == null || events.isEmpty()) {
+            return;
+        }
+        synchronized (statsQueue) {
+            statsQueue.addAll(0, events);
+        }
+        ensureStatsTimerStarted();
+    }
+
     private void runStatsCallbacks(final List<QueuedStatsEvent> sentEvents) {
         for (final QueuedStatsEvent sentEvent : sentEvents) {
             if (sentEvent.onSent == null) {

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

@@ -793,8 +793,20 @@ public class ShakeMenu implements ShakeDetector.Listener, ThreeFingerPinchDetect
 
                                 String latestUrl = getString(latestRes, "url");
 
-                                // Check if there's an actual update available
-                                if ("up_to_date".equals(latestKind) || latestUrl == null || latestUrl.isEmpty()) {
+                                Object manifestObj = latestRes.get("manifest");
+                                JSONArray manifestArray = null;
+                                if (manifestObj instanceof JSONArray) {
+                                    manifestArray = (JSONArray) manifestObj;
+                                } else if (manifestObj instanceof List) {
+                                    manifestArray = new JSONArray((List<?>) manifestObj);
+                                }
+                                final boolean hasManifest = manifestArray != null && manifestArray.length() > 0;
+
+                                // Check if there's an actual update available. A manifest-only
+                                // response legitimately has no URL (the files come from the
+                                // manifest, not a zip), so only report "already on latest" when
+                                // the URL is empty AND there is no manifest to download from.
+                                if ("up_to_date".equals(latestKind) || ((latestUrl == null || latestUrl.isEmpty()) && !hasManifest)) {
                                     activity.runOnUiThread(() -> {
                                         progressDialog.dismiss();
                                         showSuccess("Channel set to " + channelName + ". Already on latest version.");
@@ -817,25 +829,18 @@ public class ShakeMenu implements ShakeDetector.Listener, ThreeFingerPinchDetect
 
                                 String sessionKey = getString(latestRes, "sessionKey");
                                 String checksum = getString(latestRes, "checksum");
-                                Object manifestObj = latestRes.get("manifest");
+
+                                // A manifest-only response has no zip URL; downloadManifest
+                                // tolerates the placeholder URL the plugin already uses.
+                                final String downloadUrl =
+                                    latestUrl == null || latestUrl.isEmpty() ? "https://404.capgo.app/no.zip" : latestUrl;
 
                                 // Download the update
                                 try {
                                     BundleInfo bundle;
-                                    if (manifestObj != null) {
-                                        JSONArray manifestArray = null;
-                                        if (manifestObj instanceof JSONArray) {
-                                            manifestArray = (JSONArray) manifestObj;
-                                        } else if (manifestObj instanceof List) {
-                                            manifestArray = new JSONArray((List<?>) manifestObj);
-                                        }
-
-                                        if (manifestArray == null) {
-                                            throw new IllegalArgumentException("Invalid manifest format");
-                                        }
-
+                                    if (hasManifest) {
                                         bundle = updater.downloadManifest(
-                                            latestUrl,
+                                            downloadUrl,
                                             versionForUi,
                                             sessionKey != null ? sessionKey : "",
                                             checksum != null ? checksum : "",
@@ -843,7 +848,7 @@ public class ShakeMenu implements ShakeDetector.Listener, ThreeFingerPinchDetect
                                         );
                                     } else {
                                         bundle = updater.download(
-                                            latestUrl,
+                                            downloadUrl,
                                             versionForUi,
                                             sessionKey != null ? sessionKey : "",
                                             checksum != null ? checksum : ""

package/ios/Sources/CapacitorUpdaterPlugin/CapacitorUpdaterPlugin.swift

@@ -92,7 +92,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "completeFlexibleUpdate", returnType: CAPPluginReturnPromise)
     ]
     public var implementation = CapgoUpdater()
-    private let pluginVersion: String = "8.51.3"
+    private let pluginVersion: String = "8.51.5"
     private let launchStartedAtMs = Int64(Date().timeIntervalSince1970 * 1000)
     static let updateUrlDefault = "https://plugin.capgo.app/updates"
     static let statsUrlDefault = "https://plugin.capgo.app/stats"
@@ -2754,7 +2754,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
 
             let alert = UIAlertController(
                 title: "Preview started",
-                message: "Shake your device anytime to reload or leave the test app.",
+                message: self.shakeMenuGesture == Self.shakeMenuGestureThreeFingerPinch ? "Three-finger pinch to open menu." : "Shake to open menu.",
                 preferredStyle: .alert
             )
             alert.addAction(UIAlertAction(title: "Got it", style: .default))

package/ios/Sources/CapacitorUpdaterPlugin/CapgoUpdater.swift

@@ -49,12 +49,20 @@ import UIKit
     // Cached key ID calculated once from publicKey
     private var cachedKeyId: String?
 
-    // Flag to track if we received a 429 response - stops requests until app restart
-    private static var rateLimitExceeded = false
-
-    // Flag to track if we've already sent the rate limit statistic - prevents infinite loop
+    // 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 let rateLimitStateLock = NSLock()
+    private static var rateLimitBlockedUntilMs: Double = 0
+    private static var rateLimitBlockedError: String = "too_many_requests"
+    private static var rateLimitBlockedMessage: String = "Too many requests"
+
+    // 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 var rateLimitStatisticSent = false
 
+    // Upper bound for a client-side 429 block, so a bogus Retry-After cannot block the app for days.
+    private static let maxRateLimitWindowMs: Double = 24 * 60 * 60 * 1000
+
     // Stats batching - queue events and send max once per second
     private var statsQueue: [QueuedStatsEvent] = []
     private let statsQueueLock = NSLock()
@@ -421,26 +429,149 @@ import UIKit
         }
     }
 
+    private struct RemoteBlockResult {
+        let blocked: Bool
+        let error: String
+        let message: String
+    }
+
     /**
-     * Check if a 429 (Too Many Requests) response was received and set the flag
+     * Handle HTTP 429 responses by honouring Retry-After / rateLimitResetAt.
+     * All 429s use the same temporary client block — no sticky latch until restart.
      */
-    private func checkAndHandleRateLimitResponse(statusCode: Int?) -> Bool {
-        if statusCode == 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 !previewSession && !CapgoUpdater.rateLimitExceeded && !CapgoUpdater.rateLimitStatisticSent {
-                CapgoUpdater.rateLimitStatisticSent = true
-
-                // Dispatch to background queue to avoid blocking the main thread
-                DispatchQueue.global(qos: .utility).async {
-                    self.sendRateLimitStatistic()
-                }
+    private func checkAndHandleRateLimitResponse(
+        statusCode: Int?,
+        data: Data? = nil,
+        response: HTTPURLResponse? = nil
+    ) -> RemoteBlockResult {
+        guard statusCode == 429 else {
+            return RemoteBlockResult(blocked: false, error: "", message: "")
+        }
+
+        let parsed = parseRemoteError(from: data)
+        let errorCode = parsed.error.isEmpty ? "too_many_requests" : parsed.error
+        let message = parsed.message.isEmpty ? "Too many requests" : parsed.message
+
+        let retryUntilMs = resolveRateLimitBlockedUntilMs(data: data, response: response)
+        CapgoUpdater.recordRateLimitBlock(untilMs: retryUntilMs, error: errorCode, message: 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 errorCode == "too_many_requests" && !previewSession && !statsUrl.isEmpty && CapgoUpdater.claimRateLimitStatistic() {
+            DispatchQueue.global(qos: .utility).async {
+                self.sendRateLimitStatistic()
             }
-            CapgoUpdater.rateLimitExceeded = true
-            logger.warn("Rate limit exceeded (429). Stopping all stats and channel requests until app restart.")
-            return true
         }
-        return false
+
+        let nowMs = Date().timeIntervalSince1970 * 1000
+        let retryAfter = CapgoUpdater.retryAfterSecondsForLog(untilMs: retryUntilMs, nowMs: nowMs)
+        logger.warn("Received 429 (\(errorCode)). Honouring Retry-After: \(retryAfter)s.")
+        return RemoteBlockResult(blocked: true, error: errorCode, message: message)
+    }
+
+    /// Stores the block deadline and its metadata together, keeping the longest deadline
+    /// so a concurrent 429 with a shorter window cannot cut the block short.
+    private static func recordRateLimitBlock(untilMs: Double, error: String, message: String) {
+        rateLimitStateLock.lock()
+        defer { rateLimitStateLock.unlock() }
+        if untilMs > rateLimitBlockedUntilMs {
+            rateLimitBlockedUntilMs = untilMs
+            rateLimitBlockedError = error
+            rateLimitBlockedMessage = message
+        } else if rateLimitBlockedUntilMs <= 0 {
+            rateLimitBlockedError = error
+            rateLimitBlockedMessage = message
+        }
+    }
+
+    /// Seconds left in the block, clamped and finite so the Int conversion can never trap.
+    private static func retryAfterSecondsForLog(untilMs: Double, nowMs: Double) -> Int {
+        let seconds = ((untilMs - nowMs) / 1000).rounded(.up)
+        guard seconds.isFinite, seconds > 0 else {
+            return 0
+        }
+        return Int(min(seconds, maxRateLimitWindowMs / 1000))
+    }
+
+    /// Returns true for the first 429 only, so the rate-limit statistic is sent once.
+    private static func claimRateLimitStatistic() -> Bool {
+        rateLimitStateLock.lock()
+        defer { rateLimitStateLock.unlock() }
+        if rateLimitStatisticSent {
+            return false
+        }
+        rateLimitStatisticSent = true
+        return true
+    }
+
+    /// Gives the claim back when the statistic never made it out, so a later 429 can retry it.
+    private static func releaseRateLimitStatisticClaim() {
+        rateLimitStateLock.lock()
+        defer { rateLimitStateLock.unlock() }
+        rateLimitStatisticSent = false
+    }
+
+    private func parseRemoteError(from data: Data?) -> (error: String, message: String) {
+        guard let data = data,
+              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            return ("", "")
+        }
+        let error = json["error"] as? String ?? ""
+        let message = json["message"] as? String ?? ""
+        return (error, message)
+    }
+
+    private func resolveRateLimitBlockedUntilMs(data: Data?, response: HTTPURLResponse?) -> Double {
+        let nowMs = Date().timeIntervalSince1970 * 1000
+        let candidate = rawRateLimitDeadlineMs(data: data, response: response, nowMs: nowMs)
+        // NaN and past deadlines mean "no client-side block"; anything further out is capped.
+        guard candidate > nowMs else {
+            return 0
+        }
+        return min(candidate, nowMs + CapgoUpdater.maxRateLimitWindowMs)
+    }
+
+    private func rawRateLimitDeadlineMs(data: Data?, response: HTTPURLResponse?, nowMs: Double) -> Double {
+        if let header = response?.value(forHTTPHeaderField: "Retry-After")?.trimmingCharacters(in: .whitespacesAndNewlines),
+           let seconds = Double(header), seconds >= 0 {
+            return nowMs + seconds * 1000
+        }
+
+        if let data = data,
+           let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
+            let moreInfo = json["moreInfo"] as? [String: Any]
+            if let retryAfter = (moreInfo?["retryAfterSeconds"] as? NSNumber)?.doubleValue
+                ?? (json["retryAfterSeconds"] as? NSNumber)?.doubleValue,
+               retryAfter >= 0 {
+                return nowMs + retryAfter * 1000
+            }
+            if let resetAt = (moreInfo?["rateLimitResetAt"] as? NSNumber)?.doubleValue
+                ?? (json["rateLimitResetAt"] as? NSNumber)?.doubleValue {
+                return resetAt
+            }
+        }
+
+        // No retry hint — do not hold a client-side block; allow immediate retry to the worker
+        return 0
+    }
+
+    private func isRemoteBlocked() -> Bool {
+        CapgoUpdater.rateLimitStateLock.lock()
+        defer { CapgoUpdater.rateLimitStateLock.unlock() }
+        if CapgoUpdater.rateLimitBlockedUntilMs <= 0 {
+            return false
+        }
+        if Date().timeIntervalSince1970 * 1000 >= CapgoUpdater.rateLimitBlockedUntilMs {
+            CapgoUpdater.rateLimitBlockedUntilMs = 0
+            return false
+        }
+        return true
+    }
+
+    private func remoteBlockedClientError() -> (error: String, message: String) {
+        CapgoUpdater.rateLimitStateLock.lock()
+        defer { CapgoUpdater.rateLimitStateLock.unlock() }
+        return (CapgoUpdater.rateLimitBlockedError, CapgoUpdater.rateLimitBlockedMessage)
     }
 
     /**
@@ -450,6 +581,8 @@ import UIKit
      */
     private func sendRateLimitStatistic() {
         guard !statsUrl.isEmpty else {
+            // The URL was cleared after the claim was taken; nothing went out, so hand it back.
+            CapgoUpdater.releaseRateLimitStatisticClaim()
             return
         }
 
@@ -468,10 +601,16 @@ import UIKit
             encoding: JSONEncoding.default,
             requestModifier: { $0.timeoutInterval = self.timeout }
         ).responseData { response in
+            let statusCode = response.response?.statusCode
             switch response.result {
-            case .success:
+            case .success where (200...299).contains(statusCode ?? 0):
                 self.logger.info("Rate limit statistic sent")
+            case .success:
+                CapgoUpdater.releaseRateLimitStatisticClaim()
+                self.logger.error("Error sending rate limit statistic")
+                self.logger.debug("Response code: \(statusCode.map(String.init) ?? "nil")")
             case let .failure(error):
+                CapgoUpdater.releaseRateLimitStatisticClaim()
                 self.logger.error("Error sending rate limit statistic")
                 self.logger.debug("Error: \(error.localizedDescription)")
             }
@@ -825,6 +964,14 @@ import UIKit
 
     public func getLatest(url: URL, channel: String?, appIdOverride: String? = nil) -> AppVersion {
         let latest: AppVersion = AppVersion()
+        if isRemoteBlocked() {
+            let blocked = remoteBlockedClientError()
+            logger.debug("Skipping getLatest due to remote block (\(blocked.error)).")
+            latest.message = blocked.message
+            latest.error = blocked.error
+            latest.kind = "failed"
+            return latest
+        }
         func applyLatestResponse(_ value: AppVersionDec?) {
             if let url = value?.url {
                 latest.url = url
@@ -905,9 +1052,14 @@ import UIKit
             return latest
         }
 
-        if self.checkAndHandleRateLimitResponse(statusCode: latest.statusCode) {
-            latest.message = "Rate limit exceeded"
-            latest.error = "rate_limit_exceeded"
+        let rateLimit = self.checkAndHandleRateLimitResponse(
+            statusCode: latest.statusCode,
+            data: data,
+            response: result.response
+        )
+        if rateLimit.blocked {
+            latest.message = rateLimit.message
+            latest.error = rateLimit.error
             latest.kind = "failed"
             return latest
         }
@@ -2419,11 +2571,11 @@ import UIKit
             return setChannel
         }
 
-        // Check if rate limit was exceeded
-        if CapgoUpdater.rateLimitExceeded {
-            logger.debug("Skipping setChannel due to rate limit (429). Requests will resume after app restart.")
-            setChannel.message = "Rate limit exceeded"
-            setChannel.error = "rate_limit_exceeded"
+        if isRemoteBlocked() {
+            let blocked = remoteBlockedClientError()
+            logger.debug("Skipping setChannel due to remote block (\(blocked.error)).")
+            setChannel.message = blocked.message
+            setChannel.error = blocked.error
             return setChannel
         }
 
@@ -2448,9 +2600,14 @@ import UIKit
 
         let result = performRequest(request, label: "setChannel")
 
-        if self.checkAndHandleRateLimitResponse(statusCode: result.response?.statusCode) {
-            setChannel.message = "Rate limit exceeded"
-            setChannel.error = "rate_limit_exceeded"
+        let rateLimit = self.checkAndHandleRateLimitResponse(
+            statusCode: result.response?.statusCode,
+            data: result.data,
+            response: result.response
+        )
+        if rateLimit.blocked {
+            setChannel.message = rateLimit.message
+            setChannel.error = rateLimit.error
             return setChannel
         }
 
@@ -2509,10 +2666,11 @@ import UIKit
     func getChannel(defaultChannelKey: String? = nil) -> GetChannel {
         let getChannel: GetChannel = GetChannel()
         // Check if rate limit was exceeded
-        if CapgoUpdater.rateLimitExceeded {
-            logger.debug("Skipping getChannel due to rate limit (429). Requests will resume after app restart.")
-            getChannel.message = "Rate limit exceeded"
-            getChannel.error = "rate_limit_exceeded"
+        if isRemoteBlocked() {
+            let blocked = remoteBlockedClientError()
+            logger.debug("Skipping getChannel due to remote block (\(blocked.error)).")
+            getChannel.message = blocked.message
+            getChannel.error = blocked.error
             return getChannel
         }
 
@@ -2536,9 +2694,14 @@ import UIKit
 
         let result = performRequest(request, label: "getChannel")
 
-        if self.checkAndHandleRateLimitResponse(statusCode: result.response?.statusCode) {
-            getChannel.message = "Rate limit exceeded"
-            getChannel.error = "rate_limit_exceeded"
+        let rateLimit = self.checkAndHandleRateLimitResponse(
+            statusCode: result.response?.statusCode,
+            data: result.data,
+            response: result.response
+        )
+        if rateLimit.blocked {
+            getChannel.message = rateLimit.message
+            getChannel.error = rateLimit.error
             return getChannel
         }
 
@@ -2616,9 +2779,10 @@ import UIKit
         let listChannels: ListChannels = ListChannels()
 
         // Check if rate limit was exceeded
-        if CapgoUpdater.rateLimitExceeded {
-            logger.debug("Skipping listChannels due to rate limit (429). Requests will resume after app restart.")
-            listChannels.error = "rate_limit_exceeded"
+        if isRemoteBlocked() {
+            let blocked = remoteBlockedClientError()
+            logger.debug("Skipping listChannels due to remote block (\(blocked.error)).")
+            listChannels.error = blocked.error
             return listChannels
         }
 
@@ -2652,8 +2816,13 @@ import UIKit
 
         let result = performRequest(request, label: "listChannels")
 
-        if self.checkAndHandleRateLimitResponse(statusCode: result.response?.statusCode) {
-            listChannels.error = "rate_limit_exceeded"
+        let rateLimit = self.checkAndHandleRateLimitResponse(
+            statusCode: result.response?.statusCode,
+            data: result.data,
+            response: result.response
+        )
+        if rateLimit.blocked {
+            listChannels.error = rateLimit.error
             return listChannels
         }
 
@@ -2737,12 +2906,6 @@ import UIKit
             return
         }
 
-        // Check if rate limit was exceeded
-        if CapgoUpdater.rateLimitExceeded {
-            logger.debug("Skipping sendStats due to rate limit (429). Stats will resume after app restart.")
-            return
-        }
-
         guard !statsUrl.isEmpty else {
             return
         }
@@ -2795,6 +2958,12 @@ import UIKit
     }
 
     private func flushStatsQueue() {
+        // 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
+        }
+
         statsQueueLock.lock()
         guard !statsQueue.isEmpty else {
             statsQueueLock.unlock()
@@ -2805,7 +2974,6 @@ import UIKit
         statsQueueLock.unlock()
 
         let eventsToSend = queuedEvents.map(\.event)
-        let onSentCallbacks = queuedEvents.compactMap(\.onSent)
 
         operationQueue.maxConcurrentOperationCount = 1
 
@@ -2818,15 +2986,23 @@ import UIKit
                 encoder: JSONParameterEncoder.default,
                 requestModifier: { $0.timeoutInterval = self.timeout }
             ).responseData { response in
-                // Check for 429 rate limit
-                if self.checkAndHandleRateLimitResponse(statusCode: response.response?.statusCode) {
+                // Check for 429 rate limit — requeue so events are not lost.
+                if self.checkAndHandleRateLimitResponse(statusCode: response.response?.statusCode, data: response.data, response: response.response).blocked {
+                    self.requeueStatsEvents(queuedEvents)
                     semaphore.signal()
                     return
                 }
 
                 if let statusCode = response.response?.statusCode, !(200...299).contains(statusCode) {
-                    self.logger.error("Error sending stats batch")
-                    self.logger.debug("Response code: \(statusCode)")
+                    if CapgoUpdater.isTransientStatsFailure(statusCode) {
+                        self.requeueStatsEvents(queuedEvents)
+                        self.logger.error("Error sending stats batch")
+                        self.logger.debug("Retrying later, response code: \(statusCode)")
+                    } else {
+                        // Permanent rejection: retrying would loop forever and block the queue.
+                        self.logger.error("Dropping stats batch after permanent error")
+                        self.logger.debug("Response code: \(statusCode)")
+                    }
                     semaphore.signal()
                     return
                 }
@@ -2835,8 +3011,9 @@ import UIKit
                 case .success:
                     self.logger.info("Stats batch sent successfully")
                     self.logger.debug("Sent \(eventsToSend.count) events")
-                    onSentCallbacks.forEach { $0() }
+                    self.runStatsCallbacks(queuedEvents)
                 case let .failure(error):
+                    self.requeueStatsEvents(queuedEvents)
                     self.logger.error("Error sending stats batch")
                     self.logger.debug("Response: \(response.value?.debugDescription ?? "nil"), Error: \(error.localizedDescription)")
                 }
@@ -2847,6 +3024,25 @@ import UIKit
         operationQueue.addOperation(operation)
     }
 
+    /// Only 429, request timeout and 5xx are worth retrying; other 4xx are permanent rejections.
+    private static func isTransientStatsFailure(_ statusCode: Int) -> Bool {
+        return statusCode == 429 || statusCode == 408 || statusCode >= 500
+    }
+
+    private func runStatsCallbacks(_ sentEvents: [QueuedStatsEvent]) {
+        for sentEvent in sentEvents {
+            sentEvent.onSent?()
+        }
+    }
+
+    private func requeueStatsEvents(_ events: [QueuedStatsEvent]) {
+        guard !events.isEmpty else { return }
+        statsQueueLock.lock()
+        statsQueue.insert(contentsOf: events, at: 0)
+        statsQueueLock.unlock()
+        ensureStatsTimerStarted()
+    }
+
     public func getBundleInfo(id: String?) -> BundleInfo {
         var trueId = BundleInfo.VERSION_UNKNOWN
         if id != nil {

package/ios/Sources/CapacitorUpdaterPlugin/ShakeMenu.swift

@@ -726,8 +726,12 @@ extension UIWindow {
                             return
                         }
 
-                        // Check if there's an actual update available
-                        if latestKind == "up_to_date" || latest.url.isEmpty {
+                        // Check if there's an actual update available. A manifest-only
+                        // response legitimately has no URL (the files come from the
+                        // manifest, not a zip), so only report "already on latest" when
+                        // the URL is empty AND there is no manifest to download from.
+                        let hasManifest = !(latest.manifest?.isEmpty ?? true)
+                        if latestKind == "up_to_date" || (latest.url.isEmpty && !hasManifest) {
                             DispatchQueue.main.async {
                                 progressAlert.dismiss(animated: true) {
                                     self.showSuccess(message: "Channel set to \(name). Already on latest version.", plugin: plugin)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/capacitor-updater",
-  "version": "8.51.3",
+  "version": "8.51.5",
   "license": "MPL-2.0",
   "description": "Live update for capacitor apps",
   "main": "dist/plugin.cjs.js",