Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix(backend-registry): pick a healthy local backend as the fallback (#16173)

Matt Van Horne2ceffcae4f7
diff --git a/__tests__/api/backend-registry/active-store.test.ts b/__tests__/api/backend-registry/active-store.test.ts
index 8177df52ee..06a3fb9a54 100644
--- a/__tests__/api/backend-registry/active-store.test.ts
+++ b/__tests__/api/backend-registry/active-store.test.ts
@@ -9,11 +9,17 @@ import {
subscribeActiveBackend,
} from "#/api/backend-registry/active-store";
import { SEEDED_DEFAULT_BACKEND_ID } from "#/api/backend-registry/default-backend";
+import { MAX_CONSECUTIVE_FAILURES } from "#/api/backend-registry/health-storage";
+import {
+ __resetHealthStoreForTests,
+ recordBackendFailure,
+} from "#/api/backend-registry/health-store";
import type { Backend } from "#/api/backend-registry/types";
beforeEach(() => {
window.localStorage.clear();
window.sessionStorage.clear();
+ __resetHealthStoreForTests();
__resetActiveStoreForTests();
});
@@ -21,6 +27,7 @@ afterEach(() => {
window.localStorage.clear();
window.sessionStorage.clear();
vi.unstubAllEnvs();
+ __resetHealthStoreForTests();
__resetActiveStoreForTests();
});
@@ -40,6 +47,20 @@ const localBackend: Backend = {
kind: "local",
};
+const secondLocalBackend: Backend = {
+ id: "local-2",
+ name: "Local 2",
+ host: "http://localhost:9001",
+ apiKey: "k2",
+ kind: "local",
+};
+
+function markBackendUnhealthy(id: string): void {
+ for (let i = 0; i < MAX_CONSECUTIVE_FAILURES; i += 1) {
+ recordBackendFailure(id, new Error("connection failed"));
+ }
+}
+
describe("active-store", () => {
it("uses the no-backend sentinel when no backend details are available", () => {
window.localStorage.clear();
@@ -81,6 +102,41 @@ describe("active-store", () => {
expect(getActiveBackend().orgId).toBeNull();
});
+ it("falls back to a healthy local backend when a cloud backend is registered first", () => {
+ setRegisteredBackends([cloudBackend, localBackend]);
+ setActiveSelection(null);
+
+ expect(getActiveBackend().backend).toEqual(localBackend);
+ });
+
+ it("skips an unhealthy local backend in favor of a healthy one further down", () => {
+ markBackendUnhealthy(localBackend.id);
+ setRegisteredBackends([localBackend, secondLocalBackend]);
+ setActiveSelection(null);
+
+ expect(getActiveBackend().backend).toEqual(secondLocalBackend);
+ });
+
+ it("still selects a local backend when every local backend is unhealthy", () => {
+ markBackendUnhealthy(localBackend.id);
+ markBackendUnhealthy(secondLocalBackend.id);
+ setRegisteredBackends([cloudBackend, localBackend, secondLocalBackend]);
+ setActiveSelection(null);
+
+ const { backend } = getActiveBackend();
+ expect(backend.kind).toBe("local");
+ expect(backend.id).not.toBe(NO_BACKEND_ID);
+ // Deterministic: first local backend in insertion order.
+ expect(backend).toEqual(localBackend);
+ });
+
+ it("selects a single healthy local backend at the first registry position", () => {
+ setRegisteredBackends([localBackend]);
+ setActiveSelection(null);
+
+ expect(getActiveBackend().backend).toEqual(localBackend);
+ });
+
it("falls back to the first registered backend when the registry has no local entry", () => {
setRegisteredBackends([cloudBackend]);
setActiveSelection(null);
@@ -102,6 +158,15 @@ describe("active-store", () => {
expect(getEffectiveLocalBackend()).toBeNull();
});
+ it("keeps an explicit cloud selection even when a healthy local backend exists", () => {
+ setRegisteredBackends([localBackend, cloudBackend]);
+ setActiveSelection({ backendId: cloudBackend.id, orgId: "org-2" });
+
+ const { backend, orgId } = getActiveBackend();
+ expect(backend).toEqual(cloudBackend);
+ expect(orgId).toBe("org-2");
+ });
+
it("notifies subscribers when selection changes", () => {
const listener = vi.fn();
const unsubscribe = subscribeActiveBackend(listener);
diff --git a/src/api/backend-registry/active-store.ts b/src/api/backend-registry/active-store.ts
index 15baf51de9..70909053ad 100644
--- a/src/api/backend-registry/active-store.ts
+++ b/src/api/backend-registry/active-store.ts
@@ -1,3 +1,4 @@
+import { getBackendHealthEntry } from "./health-store";
import {
readStoredActiveBackend,
readStoredBackends,
@@ -33,8 +34,27 @@ export function isNoBackend(backend: Backend): boolean {
return backend.id === NO_BACKEND_ID;
}
+/**
+ * Choose an active backend when there is no valid explicit selection (fresh
+ * start, or the selected backend was removed). Most of the GUI speaks the
+ * local agent-server protocol, so a cloud or dead-local backend at index 0
+ * would leave `getEffectiveLocalBackend()` null and make every local-protocol
+ * call throw "No backend is configured" even when a healthy local backend is
+ * registered further down the list. Consult the synchronous, persisted health
+ * store and prefer a healthy local backend; fall back to any local backend so
+ * the effective-local resolver still resolves, then to the prior deterministic
+ * `backends[0]` behavior for the registry-has-no-local case.
+ */
function pickFallbackBackend(backends: Backend[]): Backend {
- return backends[0] ?? NO_BACKEND;
+ const healthyLocalBackend = backends.find(
+ (backend) =>
+ backend.kind === "local" &&
+ getBackendHealthEntry(backend.id)?.disabled !== true,
+ );
+ if (healthyLocalBackend) return healthyLocalBackend;
+
+ const localBackend = backends.find((backend) => backend.kind === "local");
+ return localBackend ?? backends[0] ?? NO_BACKEND;
}
function computeSnapshot(