Skip to content

πŸ™Œ OpenHands: AI-Driven Development

PLTF-2899: keep resume flow responsive during rate limits (#14660)

aivong-openhandscb13bd06e6ed
diff --git a/frontend/__tests__/hooks/mutation/use-unified-resume-conversation-sandbox.test.tsx b/frontend/__tests__/hooks/mutation/use-unified-resume-conversation-sandbox.test.tsx
index d11e1cac2f..51e6474802 100644
--- a/frontend/__tests__/hooks/mutation/use-unified-resume-conversation-sandbox.test.tsx
+++ b/frontend/__tests__/hooks/mutation/use-unified-resume-conversation-sandbox.test.tsx
@@ -4,17 +4,41 @@ import { describe, expect, it, vi, beforeEach } from "vitest";
import React from "react";
import { SandboxService } from "#/api/sandbox-service/sandbox-service.api";
import V1ConversationService from "#/api/conversation-service/v1-conversation-service.api";
+import { V1AppConversation } from "#/api/conversation-service/v1-conversation-service.types";
import { useUnifiedResumeConversationSandbox } from "#/hooks/mutation/use-unified-start-conversation";
// Mock the error message store
vi.mock("#/stores/error-message-store", () => ({
- useErrorMessageStore: (selector: (state: { removeErrorMessage: () => void }) => unknown) =>
- selector({ removeErrorMessage: vi.fn() }),
+ useErrorMessageStore: (
+ selector: (state: { removeErrorMessage: () => void }) => unknown,
+ ) => selector({ removeErrorMessage: vi.fn() }),
}));
describe("useUnifiedResumeConversationSandbox", () => {
let queryClient: QueryClient;
+ const createConversation = (): V1AppConversation => ({
+ id: "test-conv-id",
+ created_by_user_id: null,
+ sandbox_id: "test-sandbox-id",
+ conversation_url: "http://localhost:3000",
+ session_api_key: "test-key",
+ selected_repository: null,
+ selected_branch: null,
+ git_provider: null,
+ title: "Test",
+ public: false,
+ sandbox_status: "PAUSED",
+ execution_status: null,
+ trigger: null,
+ pr_number: [],
+ llm_model: null,
+ metrics: null,
+ sub_conversation_ids: [],
+ created_at: new Date().toISOString(),
+ updated_at: new Date().toISOString(),
+ });
+
beforeEach(() => {
queryClient = new QueryClient({
defaultOptions: {
@@ -26,45 +50,63 @@ describe("useUnifiedResumeConversationSandbox", () => {
});
const wrapper = ({ children }: { children: React.ReactNode }) => (
- <QueryClientProvider client={queryClient}>
- {children}
- </QueryClientProvider>
+ <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
);
+ it("marks the active conversation as STARTING while resume is pending", async () => {
+ const conversation = createConversation();
+ queryClient.setQueryData(
+ ["user", "conversation", conversation.id],
+ conversation,
+ );
+
+ vi.spyOn(
+ V1ConversationService,
+ "batchGetAppConversations",
+ ).mockImplementation(() => new Promise(() => {}));
+
+ const { result } = renderHook(() => useUnifiedResumeConversationSandbox(), {
+ wrapper,
+ });
+
+ result.current.mutate({ conversationId: conversation.id });
+
+ await waitFor(() => {
+ expect(
+ queryClient.getQueryData<V1AppConversation>([
+ "user",
+ "conversation",
+ conversation.id,
+ ]),
+ ).toMatchObject({
+ sandbox_status: "STARTING",
+ execution_status: null,
+ });
+ });
+ });
+
it("invalidates sandbox and vscode_url queries on settled", async () => {
// Mock the API calls in the mutation chain
- vi.spyOn(V1ConversationService, "batchGetAppConversations").mockResolvedValue([
- {
- id: "test-conv-id",
- created_by_user_id: null,
- sandbox_id: "test-sandbox-id",
- conversation_url: "http://localhost:3000",
- session_api_key: "test-key",
- selected_repository: null,
- selected_branch: null,
- git_provider: null,
- title: "Test",
- public: false,
- sandbox_status: "RUNNING",
- execution_status: null,
- trigger: null,
- pr_number: [],
- llm_model: null,
- metrics: null,
- sub_conversation_ids: [],
- created_at: new Date().toISOString(),
- updated_at: new Date().toISOString(),
- },
- ]);
- vi.spyOn(SandboxService, "resumeSandbox").mockResolvedValue({ success: true });
+ vi.spyOn(
+ V1ConversationService,
+ "batchGetAppConversations",
+ ).mockResolvedValue([createConversation()]);
+ vi.spyOn(SandboxService, "resumeSandbox").mockResolvedValue({
+ success: true,
+ });
// Pre-populate query cache with stale sandbox data
- queryClient.setQueryData(["sandboxes", "batch", ["test-sandbox-id"]], [
- {
- sandbox_id: "test-sandbox-id",
- exposed_urls: [{ name: "VSCODE", url: "https://old-runtime.example.com" }],
- },
- ]);
+ queryClient.setQueryData(
+ ["sandboxes", "batch", ["test-sandbox-id"]],
+ [
+ {
+ sandbox_id: "test-sandbox-id",
+ exposed_urls: [
+ { name: "VSCODE", url: "https://old-runtime.example.com" },
+ ],
+ },
+ ],
+ );
queryClient.setQueryData(["unified", "vscode_url", "test-conv-id"], {
url: "https://old-runtime.example.com",
error: null,
@@ -73,7 +115,9 @@ describe("useUnifiedResumeConversationSandbox", () => {
// Spy on invalidateQueries
const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
- const { result } = renderHook(() => useUnifiedResumeConversationSandbox(), { wrapper });
+ const { result } = renderHook(() => useUnifiedResumeConversationSandbox(), {
+ wrapper,
+ });
// Trigger the mutation
result.current.mutate({ conversationId: "test-conv-id" });
diff --git a/frontend/__tests__/hooks/query/use-user-conversation.test.tsx b/frontend/__tests__/hooks/query/use-user-conversation.test.tsx
new file mode 100644
index 0000000000..913d873e69
--- /dev/null
+++ b/frontend/__tests__/hooks/query/use-user-conversation.test.tsx
@@ -0,0 +1,88 @@
+import { renderHook, act } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { AxiosError } from "axios";
+import React from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import V1ConversationService from "#/api/conversation-service/v1-conversation-service.api";
+import { V1AppConversation } from "#/api/conversation-service/v1-conversation-service.types";
+import { useUserConversation } from "#/hooks/query/use-user-conversation";
+
+const createConversation = (): V1AppConversation => ({
+ id: "conversation-1",
+ created_by_user_id: null,
+ sandbox_id: "sandbox-1",
+ selected_repository: null,
+ selected_branch: null,
+ git_provider: null,
+ title: "Test conversation",
+ trigger: null,
+ pr_number: [],
+ llm_model: null,
+ metrics: null,
+ created_at: "2026-04-16T00:00:00Z",
+ updated_at: "2026-04-16T00:00:00Z",
+ sandbox_status: "PAUSED",
+ execution_status: null,
+ conversation_url: "http://localhost:3000/api/conversations/conversation-1",
+ session_api_key: "session-key",
+ sub_conversation_ids: [],
+});
+
+const createWrapper = () => {
+ const queryClient = new QueryClient({
+ defaultOptions: {
+ queries: { retry: false },
+ },
+ });
+
+ return ({ children }: { children: React.ReactNode }) => (
+ <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+ );
+};
+
+describe("useUserConversation", () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.restoreAllMocks();
+ });
+
+ it("retries rate-limited conversation fetches after the Retry-After delay", async () => {
+ const rateLimitError = {
+ response: {
+ status: 429,
+ headers: {
+ "retry-after": "1",
+ },
+ },
+ } as unknown as AxiosError;
+
+ const batchGetAppConversations = vi
+ .spyOn(V1ConversationService, "batchGetAppConversations")
+ .mockRejectedValueOnce(rateLimitError)
+ .mockResolvedValueOnce([createConversation()]);
+
+ const { result } = renderHook(() => useUserConversation("conversation-1"), {
+ wrapper: createWrapper(),
+ });
+
+ expect(batchGetAppConversations).toHaveBeenCalledTimes(1);
+
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(999);
+ });
+ expect(batchGetAppConversations).toHaveBeenCalledTimes(1);
+
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(1);
+ });
+
+ expect(batchGetAppConversations).toHaveBeenCalledTimes(2);
+ await vi.waitFor(() => {
+ expect(result.current.data?.id).toBe("conversation-1");
+ });
+ });
+});
diff --git a/frontend/__tests__/utils/rate-limit-retry.test.ts b/frontend/__tests__/utils/rate-limit-retry.test.ts
new file mode 100644
index 0000000000..54ec0f5d44
--- /dev/null
+++ b/frontend/__tests__/utils/rate-limit-retry.test.ts
@@ -0,0 +1,93 @@
+import { AxiosError } from "axios";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+ getRateLimitRetryDelayMs,
+ isRateLimitError,
+} from "#/utils/rate-limit-retry";
+
+const createAxiosError = (status: number, headers?: unknown): AxiosError =>
+ ({
+ response: {
+ status,
+ headers,
+ },
+ }) as unknown as AxiosError;
+
+describe("rate limit retry helpers", () => {
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it("recognizes response status 429 as a rate-limit error", () => {
+ expect(isRateLimitError(createAxiosError(429))).toBe(true);
+ expect(isRateLimitError(createAxiosError(500))).toBe(false);
+ });
+
+ it("uses AxiosHeaders get() before falling back to enumerable headers", () => {
+ const headers = {
+ "retry-after": "5",
+ get: (headerName: string) =>
+ headerName.toLowerCase() === "retry-after" ? "2" : undefined,
+ };
+
+ expect(getRateLimitRetryDelayMs(createAxiosError(429, headers))).toBe(2000);
+ });
+
+ it("parses Retry-After HTTP dates", () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2026-06-04T20:00:00.000Z"));
+
+ const retryAt = new Date("2026-06-04T20:00:03.000Z").toUTCString();
+
+ expect(
+ getRateLimitRetryDelayMs(
+ createAxiosError(429, {
+ "retry-after": retryAt,
+ }),
+ ),
+ ).toBe(3000);
+ });
+
+ it("falls back to one second when Retry-After is missing", () => {
+ expect(getRateLimitRetryDelayMs(createAxiosError(429))).toBe(1000);
+ });
+
+ it("falls back to one second for non-numeric Retry-After", () => {
+ expect(
+ getRateLimitRetryDelayMs(
+ createAxiosError(429, { "retry-after": "invalid" }),
+ ),
+ ).toBe(1000);
+ });
+
+ it("treats negative Retry-After seconds as immediate retry (already expired)", () => {
+ // Date.parse("-5") returns a valid timestamp (epoch - 5000ms), and since
+ // that time has passed, Math.max(negative - now, 0) returns 0
+ expect(
+ getRateLimitRetryDelayMs(createAxiosError(429, { "retry-after": "-5" })),
+ ).toBe(0);
+ });
+
+ it("treats zero Retry-After seconds as immediate (0ms delay)", () => {
+ expect(
+ getRateLimitRetryDelayMs(createAxiosError(429, { "retry-after": "0" })),
+ ).toBe(0);
+ });
+
+ it("clamps large Retry-After seconds to max 60 seconds", () => {
+ expect(
+ getRateLimitRetryDelayMs(createAxiosError(429, { "retry-after": "120" })),
+ ).toBe(60_000);
+ });
+
+ it("clamps far-future Retry-After dates to max 60 seconds", () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2026-06-04T20:00:00.000Z"));
+
+ const farFuture = new Date("2026-06-04T21:00:00.000Z").toUTCString();
+
+ expect(
+ getRateLimitRetryDelayMs(createAxiosError(429, { "retry-after": farFuture })),
+ ).toBe(60_000);
+ });
+});
diff --git a/frontend/src/hooks/mutation/use-unified-start-conversation.ts b/frontend/src/hooks/mutation/use-unified-start-conversation.ts
index 9bf2839665..3c857ea6a0 100644
--- a/frontend/src/hooks/mutation/use-unified-start-conversation.ts
+++ b/frontend/src/hooks/mutation/use-unified-start-conversation.ts
@@ -1,6 +1,11 @@
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { Provider } from "#/types/settings";
import { useErrorMessageStore } from "#/stores/error-message-store";
+import { V1AppConversation } from "#/api/conversation-service/v1-conversation-service.types";
+import {
+ getRateLimitRetryDelayMs,
+ isRateLimitError,
+} from "#/utils/rate-limit-retry";
import {
resumeV1ConversationSandbox,
updateConversationSandboxStatusInCache,
@@ -25,19 +30,41 @@ export const useUnifiedResumeConversationSandbox = () => {
);
return useMutation({
- mutationKey: ["start-conversation"],
+ // Mutation keys don't affect data cache - they only track mutation state.
+ // This key is intentionally descriptive to distinguish from any legacy mutations.
+ mutationKey: ["unified-resume-conversation-sandbox"],
mutationFn: async (variables: {
conversationId: string;
providers?: Provider[];
}) => resumeV1ConversationSandbox(variables.conversationId),
- onMutate: async () => {
+ retry: (failureCount, error) => isRateLimitError(error) && failureCount < 3,
+ retryDelay: (_failureCount, error) => getRateLimitRetryDelayMs(error),
+ onMutate: async (variables) => {
await queryClient.cancelQueries({ queryKey: ["user", "conversations"] });
const previousConversations = queryClient.getQueryData([
"user",
"conversations",
]);
+ const previousConversation =
+ queryClient.getQueryData<V1AppConversation | null>([
+ "user",
+ "conversation",
+ variables.conversationId,
+ ]);
+
+ queryClient.setQueryData<V1AppConversation | null>(
+ ["user", "conversation", variables.conversationId],
+ (oldData) =>
+ oldData
+ ? {
+ ...oldData,
+ sandbox_status: "STARTING",
+ execution_status: null,
+ }
+ : oldData,
+ );
- return { previousConversations };
+ return { previousConversations, previousConversation };
},
onError: (_, __, context) => {
if (context?.previousConversations) {
@@ -46,6 +73,12 @@ export const useUnifiedResumeConversationSandbox = () => {
context.previousConversations,
);
}
+ if (context?.previousConversation) {
+ queryClient.setQueryData(
+ ["user", "conversation", context.previousConversation.id],
+ context.previousConversation,
+ );
+ }
},
onSettled: (_, __, variables) => {
invalidateConversationQueries(queryClient, variables.conversationId);
diff --git a/frontend/src/hooks/query/use-user-conversation.ts b/frontend/src/hooks/query/use-user-conversation.ts
index af6a31a922..afb780b0bd 100644
--- a/frontend/src/hooks/query/use-user-conversation.ts
+++ b/frontend/src/hooks/query/use-user-conversation.ts
@@ -3,6 +3,10 @@ import { Query, useQuery } from "@tanstack/react-query";
import { AxiosError } from "axios";
import V1ConversationService from "#/api/conversation-service/v1-conversation-service.api";
import { V1AppConversation } from "#/api/conversation-service/v1-conversation-service.types";
+import {
+ getRateLimitRetryDelayMs,
+ isRateLimitError,
+} from "#/utils/rate-limit-retry";
const FIVE_MINUTES = 1000 * 60 * 5;
const FIFTEEN_MINUTES = 1000 * 60 * 15;
@@ -32,7 +36,8 @@ export const useUserConversation = (
return results[0] ?? null;
},
enabled: !!cid && !cid.startsWith("task-"),
- retry: false,
+ retry: (failureCount, error) => isRateLimitError(error) && failureCount < 3,
+ retryDelay: (_failureCount, error) => getRateLimitRetryDelayMs(error),
refetchInterval,
staleTime: FIVE_MINUTES,
gcTime: FIFTEEN_MINUTES,
diff --git a/frontend/src/utils/rate-limit-retry.ts b/frontend/src/utils/rate-limit-retry.ts
new file mode 100644
index 0000000000..c497076b5c
--- /dev/null
+++ b/frontend/src/utils/rate-limit-retry.ts
@@ -0,0 +1,61 @@
+import { AxiosError } from "axios";
+
+const DEFAULT_RETRY_AFTER_MS = 1000;
+const MAX_RETRY_DELAY_MS = 60_000;
+const RETRY_AFTER_HEADER = "retry-after";
+
+function getHeaderValue(headers: unknown, name: string): string | undefined {
+ if (!headers || typeof headers !== "object") {
+ return undefined;
+ }
+
+ if (
+ "get" in headers &&
+ typeof (headers as { get: (headerName: string) => unknown }).get ===
+ "function"
+ ) {
+ const value = (headers as { get: (headerName: string) => unknown }).get(
+ name,
+ );
+ return typeof value === "string" ? value : undefined;
+ }
+
+ const matchingHeader = Object.entries(headers).find(
+ ([key]) => key.toLowerCase() === name,
+ )?.[1];
+
+ if (typeof matchingHeader === "number") {
+ return String(matchingHeader);
+ }
+
+ return typeof matchingHeader === "string" ? matchingHeader : undefined;
+}
+
+export function isRateLimitError(error: unknown): boolean {
+ const axiosError = error as AxiosError | undefined;
+ return axiosError?.response?.status === 429 || axiosError?.status === 429;
+}
+
+export function getRateLimitRetryDelayMs(error: unknown): number {
+ const axiosError = error as AxiosError | undefined;
+ const retryAfter = getHeaderValue(
+ axiosError?.response?.headers,
+ RETRY_AFTER_HEADER,
+ );
+
+ if (!retryAfter) {
+ return DEFAULT_RETRY_AFTER_MS;
+ }
+
+ const seconds = Number(retryAfter);
+ if (Number.isFinite(seconds) && seconds >= 0) {
+ return Math.min(seconds * 1000, MAX_RETRY_DELAY_MS);
+ }
+
+ const retryAt = Date.parse(retryAfter);
+ if (Number.isNaN(retryAt)) {
+ return DEFAULT_RETRY_AFTER_MS;
+ }
+
+ return Math.min(Math.max(retryAt - Date.now(), 0), MAX_RETRY_DELAY_MS);
+}
diff --git a/openhands/app_server/middleware.py b/openhands/app_server/middleware.py
index c750e000d5..2ff6d325cc 100644
--- a/openhands/app_server/middleware.py
+++ b/openhands/app_server/middleware.py
@@ -1,5 +1,6 @@
import asyncio
import logging
+import re
from collections import defaultdict
from datetime import datetime, timedelta
from urllib.parse import urlparse
@@ -14,6 +15,8 @@ from starlette.types import ASGIApp
from openhands.app_server.config import get_global_config
+_RESUME_RE = re.compile(r'^/api/v1/sandboxes/[^/]+/resume/?$')
+
class LocalhostCORSMiddleware(CORSMiddleware):
"""Custom CORS middleware that allows any request from localhost/127.0.0.1 domains,
@@ -83,7 +86,6 @@ class InMemoryRateLimiter:
self.seconds = seconds
self.sleep_seconds = sleep_seconds
self.history = defaultdict(list)
- self.sleep_seconds = sleep_seconds
def _clean_old_requests(self, key: str) -> None:
now = datetime.now()
@@ -130,7 +132,10 @@ class RateLimitMiddleware(BaseHTTPMiddleware):
return await call_next(request)
def is_rate_limited_request(self, request: StarletteRequest) -> bool:
- if request.url.path.startswith('/assets'):
- return False
- # Put Other non rate limited checks here
- return True
+ return not (
+ request.url.path.startswith('/assets')
+ or self._is_sandbox_resume_request(request)
+ )
+
+ def _is_sandbox_resume_request(self, request: StarletteRequest) -> bool:
+ return request.method == 'POST' and bool(_RESUME_RE.match(request.url.path))
diff --git a/tests/unit/server/test_middleware.py b/tests/unit/server/test_middleware.py
index aab59d677b..3a47d6b2b6 100644
--- a/tests/unit/server/test_middleware.py
+++ b/tests/unit/server/test_middleware.py
@@ -5,7 +5,11 @@ from fastapi import FastAPI
from fastapi.testclient import TestClient
from starlette.middleware.cors import CORSMiddleware
-from openhands.app_server.middleware import LocalhostCORSMiddleware
+from openhands.app_server.middleware import (
+ InMemoryRateLimiter,
+ LocalhostCORSMiddleware,
+ RateLimitMiddleware,
+)
@pytest.fixture
@@ -150,3 +154,29 @@ def test_localhost_cors_middleware_cors_parameters():
assert kwargs['allow_credentials'] is True
assert kwargs['allow_methods'] == ['*']
assert kwargs['allow_headers'] == ['*']
+
+
+def test_rate_limit_middleware_exempts_sandbox_resume():
+ """Resume requests should not compete with bursty reopen polling."""
+ app = FastAPI()
+
+ @app.post('/api/v1/sandboxes/{sandbox_id}/resume')
+ def resume_sandbox(sandbox_id: str):
+ return {'sandbox_id': sandbox_id}
+
+ @app.get('/api/v1/app-conversations')
+ def batch_get_app_conversations(ids: str):
+ return {'ids': ids}
+
+ app.add_middleware(
+ RateLimitMiddleware,
+ rate_limiter=InMemoryRateLimiter(requests=0, seconds=60, sleep_seconds=0),
+ )
+ client = TestClient(app)
+
+ rate_limited_response = client.get('/api/v1/app-conversations?ids=conv-123')
+ resume_response = client.post('/api/v1/sandboxes/sandbox-123/resume')
+
+ assert rate_limited_response.status_code == 429
+ assert resume_response.status_code == 200
+ assert resume_response.json() == {'sandbox_id': 'sandbox-123'}