Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Fix Admin restart recovery and graceful shutdown (#1669)

Ali Khokhar2bc642b3bc6f
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 9ffb8b4d..1e229262 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -256,6 +256,11 @@ transcriber, `ApplicationRuntime`, `ApiServices`, and ASGI application.
[runtime/asgi.py](src/free_claude_code/runtime/asgi.py) drives runtime startup and
shutdown through lifespan events.
+The supervised `RuntimeServer` first signals `ApplicationRuntime.begin_shutdown`.
+Chat stops admitting work and finishes its observer feeds before Uvicorn drains
+HTTP connections. Chat operations can still settle and publish internally;
+storage and provider resources remain owned until lifespan cleanup completes.
+
[runtime/provider_manager.py](src/free_claude_code/runtime/provider_manager.py)
alone publishes, retires, and closes provider generations. Each inference request
holds a settings/provider snapshot through a lease. Provider-only Admin Apply
@@ -286,6 +291,7 @@ client executables and native client state have separate owners.
Lifecycle behavior is covered by
[runtime tests](tests/runtime/test_application_runtime.py),
+[supervised HTTP shutdown tests](tests/cli/test_server_shutdown.py),
[provider-manager tests](tests/runtime/test_provider_manager.py), and
[response-stream tests](tests/api/test_response_streams.py).
@@ -328,6 +334,12 @@ key. Accepted changes either replace a provider generation or follow the runtime
restart path. Configuration readiness, live provider checks, and discovery are
separate states.
+Automatic restart responses identify the old runtime instance. Admin polls the
+local status endpoint until a different running instance is ready, then reloads
+settings and retains credential warnings. A bounded reconnect failure offers a
+retry without resubmitting edits. Status allows reads from validated loopback
+origins so this also works when Apply changes the server address.
+
Authentication is defined in
[api/dependencies.py](src/free_claude_code/api/dependencies.py):
diff --git a/e2e/test_admin_apply.py b/e2e/test_admin_apply.py
index ed5d26b5..b80bb34d 100644
--- a/e2e/test_admin_apply.py
+++ b/e2e/test_admin_apply.py
@@ -104,6 +104,7 @@ def test_unverified_warning_survives_apply(
"required": restart,
"automatic": restart,
"admin_url": "/admin",
+ "instance_id": "old-server",
},
"credential_checks": [
{
@@ -115,19 +116,21 @@ def test_unverified_warning_survives_apply(
}
),
)
+ page.route(
+ "**/admin/api/status",
+ lambda route: route.fulfill(
+ json={"status": "running", "instance_id": "new-server"}
+ ),
+ )
page.goto(f"{admin_base_url}/admin")
expect(page.locator("#messageArea")).to_have_text("")
page.locator("#field-NVIDIA_NIM_API_KEY").fill("new-key")
page.get_by_role("button", name="Apply", exact=True).click()
expect(page.locator("#messageArea")).to_contain_text("Verification unavailable.")
- if restart:
- expect(
- page.get_by_role("link", name="Open Admin", exact=True)
- ).to_have_attribute("href", "/admin")
- expect(page.locator("#applyButton")).to_be_disabled()
- else:
- expect(page.locator("#dirtyState")).to_have_text("No changes")
- expect(page.locator("#field-NVIDIA_NIM_API_KEY")).to_be_editable()
+ expect(page.locator("#dirtyState")).to_have_text("No changes")
+ expect(page.locator("#field-NVIDIA_NIM_API_KEY")).to_be_editable()
+ expect(page.locator("#applyButton")).to_have_text("Apply")
+ expect(page.locator("#messageArea")).to_contain_text("Verification unavailable.")
def test_apply_network_error_unlocks_form_and_keeps_edits(
@@ -143,3 +146,147 @@ def test_apply_network_error_unlocks_form_and_keeps_edits(
expect(key).to_have_value("unsaved-key")
expect(key).to_be_editable()
expect(page.locator("#applyButton")).to_be_enabled()
+
+
+def test_restart_waits_for_a_new_running_server(page: Page, admin_base_url: str):
+ pending: list[Route] = []
+ page.route("**/admin/api/status", lambda route: pending.append(route))
+ page.route(
+ "**/admin/api/config/apply",
+ lambda route: route.fulfill(
+ json={
+ "applied": True,
+ "restart": {
+ "required": True,
+ "automatic": True,
+ "admin_url": "/admin",
+ "fields": ["NVIDIA_NIM_API_KEY"],
+ "instance_id": "old-server",
+ },
+ "credential_checks": [],
+ }
+ ),
+ )
+ page.goto(f"{admin_base_url}/admin")
+ expect(page.locator("#messageArea")).to_have_text("")
+ page.locator("#field-NVIDIA_NIM_API_KEY").fill("new-key")
+ with page.expect_request("**/admin/api/status"):
+ page.get_by_role("button", name="Apply", exact=True).click()
+ expect(page.locator("#applyButton")).to_have_text("Reconnecting…")
+ for status in (
+ {"status": "running", "instance_id": "old-server"},
+ {"status": "stopping", "instance_id": "new-server"},
+ ):
+ with page.expect_request("**/admin/api/status"):
+ pending.pop(0).fulfill(json=status)
+ expect(page.locator("#view-providers")).to_have_attribute("inert", "")
+ expect(page.locator("#dirtyState")).to_have_text("Changes saved")
+ pending.pop(0).fulfill(json={"status": "running", "instance_id": "new-server"})
+ expect(page.locator("#field-NVIDIA_NIM_API_KEY")).to_be_editable()
+ expect(page.locator("#dirtyState")).to_have_text("No changes")
+ expect(page.locator("#messageArea")).to_have_text("Applied")
+
+
+def test_restart_timeout_can_reconnect_without_resubmitting_keys(
+ page: Page, admin_base_url: str
+):
+ ready = False
+ submissions: list[object] = []
+
+ def apply_result(route: Route):
+ submissions.append(route.request.post_data_json)
+ route.fulfill(
+ json={
+ "applied": True,
+ "restart": {
+ "required": True,
+ "automatic": True,
+ "admin_url": "/admin",
+ "fields": ["NVIDIA_NIM_API_KEY"],
+ "instance_id": "old-server",
+ },
+ "credential_checks": [
+ {
+ "key": "NVIDIA_NIM_API_KEY",
+ "status": "unverified",
+ "message": "Verification unavailable.",
+ }
+ ],
+ }
+ )
+
+ def status_result(route: Route):
+ if ready:
+ route.fulfill(json={"status": "running", "instance_id": "new-server"})
+ else:
+ route.abort()
+
+ page.route("**/admin/api/config/apply", apply_result)
+ page.route("**/admin/api/status", status_result)
+ page.goto(f"{admin_base_url}/admin")
+ expect(page.locator("#messageArea")).to_have_text("")
+ page.clock.install()
+ page.locator("#field-NVIDIA_NIM_API_KEY").fill("new-key")
+ with page.expect_request("**/admin/api/status"):
+ page.get_by_role("button", name="Apply", exact=True).click()
+ expect(page.locator("#applyButton")).to_have_text("Reconnecting…")
+ page.clock.fast_forward(31_000)
+ page.clock.run_for(1_000)
+ reconnect = page.get_by_role("button", name="Reconnect", exact=True)
+ expect(reconnect).to_be_enabled()
+ expect(page.locator("#messageArea")).to_contain_text("Settings were saved")
+ expect(page.locator("#messageArea")).to_contain_text("Verification unavailable.")
+ expect(page.locator("#view-providers")).to_have_attribute("inert", "")
+ expect(page.get_by_role("link", name="Open Admin")).to_have_attribute(
+ "href", f"{admin_base_url}/admin"
+ )
+ ready = True
+ reconnect.click()
+ expect(page.locator("#field-NVIDIA_NIM_API_KEY")).to_be_editable()
+ expect(page.locator("#messageArea")).to_contain_text("Verification unavailable.")
+ assert submissions == [{"values": {"NVIDIA_NIM_API_KEY": "new-key"}}]
+
+
+def test_restart_to_another_local_origin_keeps_the_warning(
+ page: Page, admin_base_url: str
+):
+ target = admin_base_url.replace("127.0.0.1", "localhost") + "/admin"
+ page.route(
+ "**/admin/api/config/apply",
+ lambda route: route.fulfill(
+ json={
+ "applied": True,
+ "restart": {
+ "required": True,
+ "automatic": True,
+ "admin_url": target,
+ "fields": ["HOST"],
+ "instance_id": "old-server",
+ },
+ "credential_checks": [
+ {
+ "key": "NVIDIA_NIM_API_KEY",
+ "status": "unverified",
+ "message": "Verification unavailable.",
+ }
+ ],
+ }
+ ),
+ )
+ page.route(
+ "**/admin/api/status",
+ lambda route: route.fulfill(
+ headers={"Access-Control-Allow-Origin": admin_base_url},
+ json={"status": "running", "instance_id": "new-server"},
+ ),
+ )
+ page.goto(f"{admin_base_url}/admin")
+ expect(page.locator("#messageArea")).to_have_text("")
+ page.locator("#field-NVIDIA_NIM_API_KEY").fill("new-key")
+ page.get_by_role("button", name="Apply", exact=True).click()
+ page.wait_for_url(target)
+ expect(page.locator("#field-NVIDIA_NIM_API_KEY")).to_be_editable()
+ expect(page.locator("#messageArea")).to_contain_text("Verification unavailable.")
+ assert "new-key" not in page.url
+ page.reload()
+ expect(page.locator("#messageArea")).to_have_text("")
diff --git a/pyproject.toml b/pyproject.toml
index 5f72706d..9d997480 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "5.21.0"
+version = "5.21.1"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/api/admin_routes.py b/src/free_claude_code/api/admin_routes.py
index 3b2fd9b5..fbb89588 100644
--- a/src/free_claude_code/api/admin_routes.py
+++ b/src/free_claude_code/api/admin_routes.py
@@ -5,7 +5,14 @@ from collections.abc import Mapping
from pathlib import Path
import httpx
-from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request
+from fastapi import (
+ APIRouter,
+ BackgroundTasks,
+ Depends,
+ HTTPException,
+ Request,
+ Response,
+)
from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
from loguru import logger
from pydantic import BaseModel, Field
@@ -122,9 +129,15 @@ async def apply_admin_config(
@router.get("/admin/api/status")
async def admin_status(
request: Request,
+ response: Response,
services: ApiServices = Depends(get_services),
):
require_loopback_admin(request)
+ # A local Admin page may reconnect after Apply changes the listening port.
+ # The existing security check admits only loopback callers and origins.
+ if origin := request.headers.get("origin"):
+ response.headers["Access-Control-Allow-Origin"] = origin
+ response.headers["Vary"] = "Origin"
return services.admin.admin_status()
diff --git a/src/free_claude_code/api/admin_static/admin.js b/src/free_claude_code/api/admin_static/admin.js
index 8b91b31d..494064ba 100644
--- a/src/free_claude_code/api/admin_static/admin.js
+++ b/src/free_claude_code/api/admin_static/admin.js
@@ -1,6 +1,7 @@
const state = {
config: null,
applying: false,
+ restart: null,
fields: new Map(),
modelOptions: [],
modelComboboxes: new Set(),
@@ -887,8 +888,8 @@ function changedValues() {
function updateDirtyState() {
const count = Object.keys(changedValues()).length;
byId("dirtyState").textContent =
- count === 0 ? "No changes" : `${count} unsaved change${count === 1 ? "" : "s"}`;
- byId("applyButton").disabled = state.applying || count === 0;
+ state.restart ? "Changes saved" : count === 0 ? "No changes" : `${count} unsaved change${count === 1 ? "" : "s"}`;
+ byId("applyButton").disabled = state.applying || (!state.restart && count === 0);
}
function clearCredentialError(input) {
@@ -919,15 +920,93 @@ function showCredentialErrors(checks) {
function setApplying(applying) {
state.applying = applying;
VIEW_GROUPS.filter((view) => view.id !== "chat").forEach((view) => {
- byId(`view-${view.id}`).inert = applying;
+ byId(`view-${view.id}`).inert = applying || !!state.restart;
});
if (applying) state.modelComboboxes.forEach((combobox) => combobox.close());
- byId("applyButton").textContent = applying ? "Applying…" : "Apply";
+ byId("applyButton").textContent = state.restart
+ ? applying ? "Reconnecting…" : "Reconnect"
+ : applying ? "Applying…" : "Apply";
updateDirtyState();
}
+async function waitForRestart(restart, target) {
+ const deadline = performance.now() + 30_000;
+ const statusUrl = new URL("/admin/api/status", target);
+ while (performance.now() < deadline) {
+ try {
+ const response = await fetch(statusUrl, {
+ cache: "no-store",
+ credentials: "omit",
+ signal: AbortSignal.timeout(1500),
+ });
+ if (response.ok) {
+ const status = await response.json();
+ if (status.status === "running" && typeof status.instance_id === "string"
+ && status.instance_id !== restart.instance_id) return;
+ }
+ } catch {
+ // Closing listeners and unfinished startup are expected during a restart.
+ }
+ await new Promise((resolve) => setTimeout(resolve, 250));
+ }
+ throw new Error("The server has not reconnected yet.");
+}
+
+function appendAdminLink(target) {
+ const link = document.createElement("a");
+ link.href = target.href;
+ link.textContent = "Open Admin";
+ byId("messageArea").append(document.createElement("br"), link);
+}
+
+async function reconnectAfterRestart() {
+ const { restart, warnings } = state.restart;
+ const target = new URL(restart.admin_url || "/admin", window.location.href);
+ setApplying(true);
+ showMessage(["Applied. Reconnecting to the server…", ...warnings].join("\n"), warnings.length ? "warn" : "ok");
+ try {
+ await waitForRestart(restart, target);
+ if (target.origin !== window.location.origin) {
+ // Carry only the safe warning text across an address change, never edits.
+ target.hash = new URLSearchParams({ "fcc-applied": JSON.stringify(warnings) }).toString();
+ window.location.replace(target.href);
+ return;
+ }
+ await load();
+ state.restart = null;
+ showMessage(["Applied", ...warnings].join("\n"), warnings.length ? "warn" : "ok");
+ } catch (error) {
+ showMessage([`Settings were saved. ${error.message} Use Reconnect to try again.`, ...warnings].join("\n"), "warn");
+ appendAdminLink(target);
+ } finally {
+ setApplying(false);
+ }
+}
+
+function showRestartNotice() {
+ const url = new URL(window.location.href);
+ const fragment = new URLSearchParams(url.hash.slice(1));
+ const notice = fragment.get("fcc-applied");
+ if (notice === null) return;
+ fragment.delete("fcc-applied");
+ url.hash = fragment.toString();
+ window.history.replaceState(window.history.state, "", url);
+ try {
+ const warnings = JSON.parse(notice);
+ if (Array.isArray(warnings) && warnings.every((warning) => typeof warning === "string")) {
+ showMessage(["Applied", ...warnings].join("\n"), warnings.length ? "warn" : "ok");
+ }
+ } catch {
+ // A malformed navigation notice must not prevent normal Admin use.
+ }
+}
+
async function apply() {
if (state.applying) return;
+ if (state.restart) {
+ await reconnectAfterRestart();
+ return;
+ }
const values = changedValues();
if (!Object.keys(values).length) return;
const checkingKeys = Object.keys(values).some((key) => {
@@ -936,7 +1015,6 @@ async function apply() {
});
let rejectedField = null;
let applied = false;
- let restarting = false;
setApplying(true);
showMessage(checkingKeys ? "Checking API keys…" : "Applying…");
try {
@@ -956,18 +1034,8 @@ async function apply() {
);
const restart = result.restart || {};
if (restart.required && restart.automatic) {
- restarting = true;
- showMessage(["Applied. Restarting server…", ...warnings].join("\n"), warnings.length ? "warn" : "ok");
- if (warnings.length) {
- const link = document.createElement("a");
- link.href = restart.admin_url || "/admin";
- link.textContent = "Open Admin";
- byId("messageArea").append(document.createElement("br"), link);
- } else {
- setTimeout(() => {
- window.location.href = restart.admin_url || "/admin";
- }, 1600);
- }
+ state.restart = { restart, warnings };
+ await reconnectAfterRestart();
return;
}
const pending = restart.required ? restart.fields || [] : result.pending_fields || [];
@@ -979,8 +1047,7 @@ async function apply() {
} catch (error) {
showMessage(applied ? `Applied, but could not reload settings: ${error.message}` : `Could not apply settings: ${error.message}`, "error");
} finally {
- // Keep the old page read-only while its server restarts.
- setApplying(restarting);
+ setApplying(false);
if (rejectedField) {
navigateToView("providers");
rejectedField.closest(".settings-section")?.classList.add("show-advanced");
@@ -1131,6 +1198,6 @@ window.addEventListener("popstate", () => {
setActiveView(viewId, { scroll: false });
});
-load().catch((error) => {
+load().then(showRestartNotice).catch((error) => {
showMessage(error.message, "error");
});
diff --git a/src/free_claude_code/application/chat/events.py b/src/free_claude_code/application/chat/events.py
index c2c5c27c..feca8a4e 100644
--- a/src/free_claude_code/application/chat/events.py
+++ b/src/free_claude_code/application/chat/events.py
@@ -111,6 +111,10 @@ class ChatEventPublisher:
if self._closed:
return
self._closed = True
+ self.disconnect_subscribers()
+
+ def disconnect_subscribers(self) -> None:
+ """Finish observer feeds while allowing owned work to settle and publish."""
subscriptions = tuple(self._subscriptions)
self._subscriptions.clear()
for subscription in subscriptions:
diff --git a/src/free_claude_code/application/chat/service.py b/src/free_claude_code/application/chat/service.py
index fe52031a..4d2cf64f 100644
--- a/src/free_claude_code/application/chat/service.py
+++ b/src/free_claude_code/application/chat/service.py
@@ -201,6 +201,12 @@ class ChatService:
await self._store.close()
self._started = False
+ def begin_shutdown(self) -> None:
+ """Stop new Chat work and finish feeds before HTTP connections drain."""
+ self._accepting = False
+ self._unavailable_message = "Chat Sessions is stopping."
+ self._events.disconnect_subscribers()
+
async def close(self) -> None:
self._accepting = False
async with self._active_lock:
diff --git a/src/free_claude_code/cli/commands.py b/src/free_claude_code/cli/commands.py
index 4a16c676..587e8d87 100644
--- a/src/free_claude_code/cli/commands.py
+++ b/src/free_claude_code/cli/commands.py
@@ -1,8 +1,10 @@
"""Implementations for installed Free Claude Code commands."""
+import socket
import threading
import time
import webbrowser
+from collections.abc import Callable
from enum import StrEnum
import uvicorn
@@ -37,6 +39,20 @@ class ServerStatus(StrEnum):
STOPPED = "Stopped"
+class RuntimeServer(uvicorn.Server):
+ """Notify the runtime before Uvicorn waits for long-lived HTTP responses."""
+
+ def __init__(
+ self, config: uvicorn.Config, *, begin_shutdown: Callable[[], None]
+ ) -> None:
+ super().__init__(config)
+ self._begin_shutdown = begin_shutdown
+
+ async def shutdown(self, sockets: list[socket.socket] | None = None) -> None:
+ self._begin_shutdown()
+ await super().shutdown(sockets)
+
+
class ServerSupervisor:
"""Own one FCC server lifecycle, including config-driven restarts."""
@@ -162,7 +178,7 @@ class ServerSupervisor:
),
timeout_graceful_shutdown=SERVER_GRACEFUL_SHUTDOWN_SECONDS,
)
- server = uvicorn.Server(config)
+ server = RuntimeServer(config, begin_shutdown=asgi_app.runtime.begin_shutdown)
with self._lock:
self._server = server
if self._stop_requested or self._restart_generation != restart_generation:
diff --git a/src/free_claude_code/runtime/application.py b/src/free_claude_code/runtime/application.py
index c3d968e5..64d5a827 100644
--- a/src/free_claude_code/runtime/application.py
+++ b/src/free_claude_code/runtime/application.py
@@ -5,6 +5,7 @@ import inspect
import logging
import os
import traceback
+import uuid
from collections.abc import Awaitable, Callable, Mapping
from dataclasses import replace
@@ -128,6 +129,8 @@ class ApplicationRuntime:
)
self._cli_manager: cli_managed.ManagedClaudeSessionManager | None = None
self._started = False
+ self._instance_id = uuid.uuid4().hex
+ self._draining = False
self._closed = False
self._provider_manager_closed = False
self._connected_accounts_closed = False
@@ -168,6 +171,12 @@ class ApplicationRuntime:
await self.close()
raise
+ def begin_shutdown(self) -> None:
+ """Finish indefinite observer responses before the server drains HTTP."""
+ self._draining = True
+ if self._chat_service is not None:
+ self._chat_service.begin_shutdown()
+
async def close(self) -> bool:
async with self._close_lock:
if self._closed:
@@ -246,7 +255,8 @@ class ApplicationRuntime:
def admin_status(self) -> JsonObject:
settings = self.settings
return {
- "status": "running",
+ "status": "stopping" if self._draining else "running",
+ "instance_id": self._instance_id,
"host": settings.host,
"port": settings.port,
"model": settings.model,
@@ -362,12 +372,15 @@ class ApplicationRuntime:
settings: Settings,
) -> JsonObject:
automatic = bool(fields and self._restart_callback is not None)
- return {
+ result: JsonObject = {
"required": bool(fields),
"automatic": automatic,
"admin_url": local_admin_url(settings) if automatic else None,
"fields": list(fields),
}
+ if automatic:
+ result["instance_id"] = self._instance_id
+ return result
async def _start_messaging_if_configured(self) -> None:
try:
diff --git a/tests/api/test_admin.py b/tests/api/test_admin.py
index 047cca6d..7c18c9fc 100644
--- a/tests/api/test_admin.py
+++ b/tests/api/test_admin.py
@@ -1668,6 +1668,7 @@ def test_admin_apply_restart_required_reports_automatic_restart(monkeypatch, tmp
callbacks.append("restart")
app = create_test_app(restart_callback=restart_callback)
+ instance_id = _local_client(app).get("/admin/api/status").json()["instance_id"]
response = _local_client(app).post(
"/admin/api/config/apply",
@@ -1683,10 +1684,35 @@ def test_admin_apply_restart_required_reports_automatic_restart(monkeypatch, tmp
"automatic": True,
"admin_url": "http://127.0.0.1:9090/admin",
"fields": ["PORT"],
+ "instance_id": instance_id,
}
assert callbacks == ["restart"]
[email protected]("origin", ["http://127.0.0.1:8082", "http://localhost:9090"])
+def test_admin_restart_status_can_be_read_from_another_local_address(origin):
+ app = create_test_app()
+ response = _local_client(app).get("/admin/api/status", headers={"Origin": origin})
+ assert response.status_code == 200
+ assert response.headers["Access-Control-Allow-Origin"] == origin
+ assert response.headers["Vary"] == "Origin"
+ initial = response.json()
+ assert initial["status"] == "running"
+ assert isinstance(initial["instance_id"], str) and initial["instance_id"]
+ runtime_for_app(app).begin_shutdown()
+ stopping = _local_client(app).get("/admin/api/status").json()
+ assert stopping["status"] == "stopping"
+ assert stopping["instance_id"] == initial["instance_id"]
+
+
+def test_admin_restart_status_does_not_allow_a_remote_web_origin():
+ response = _local_client(create_test_app()).get(
+ "/admin/api/status", headers={"Origin": "https://example.com"}
+ )
+ assert response.status_code == 403
+ assert "Access-Control-Allow-Origin" not in response.headers
+
+
def test_admin_apply_restart_required_reports_manual_fallback(monkeypatch, tmp_path):
_set_home(monkeypatch, tmp_path)
_clear_process_config(monkeypatch)
diff --git a/tests/application/test_chat_service.py b/tests/application/test_chat_service.py
index b37a3ce6..a69778d9 100644
--- a/tests/application/test_chat_service.py
+++ b/tests/application/test_chat_service.py
@@ -1820,7 +1820,10 @@ async def test_cancelled_delete_request_still_finishes_accepted_deletion(
@pytest.mark.asyncio
-async def test_close_waits_for_terminal_settlement(tmp_path: Path, monkeypatch):
[email protected]("drain_feeds", [False, True])
+async def test_close_waits_for_terminal_settlement(
+ tmp_path: Path, monkeypatch, drain_feeds
+):
service, _runtime, store = await _service(tmp_path, FakeChatProvider())
release_commit = asyncio.Event()
service_closed = False
@@ -1846,6 +1849,17 @@ async def test_close_waits_for_terminal_settlement(tmp_path: Path, monkeypatch):
)
await asyncio.wait_for(entered_commit.wait(), timeout=1)
+ if drain_feeds:
+ service.begin_shutdown()
+ service.begin_shutdown()
+ assert service.availability()[0] is False
+ with pytest.raises(ChatUnavailableError):
+ await service.subscribe()
+ with pytest.raises(StopAsyncIteration):
+ await asyncio.wait_for(
+ anext(stream.subscription.__aiter__()), timeout=1
+ )
+
close_task = asyncio.create_task(service.close())
await asyncio.sleep(0.05)
assert not close_task.done()
diff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.py
index ae75ccd0..e3e9ae68 100644
--- a/tests/cli/test_entrypoints.py
+++ b/tests/cli/test_entrypoints.py
@@ -333,12 +333,14 @@ def test_serve_supervisor_restarts_when_app_requests_restart() -> None:
def build_asgi_app(_settings: Settings, restart_callback: Callable[[], None]):
restart_callbacks.append(restart_callback)
- app = SimpleNamespace(runtime=SimpleNamespace(is_closed=False))
+ app = SimpleNamespace(
+ runtime=SimpleNamespace(is_closed=False, begin_shutdown=lambda: None)
+ )
apps.append(app)
return app
class FakeServer:
- def __init__(self, config):
+ def __init__(self, config, *, begin_shutdown):
self.config = config
self.should_exit = False
servers.append(self)
@@ -355,7 +357,7 @@ def test_serve_supervisor_restarts_when_app_requests_restart() -> None:
with (
patch.object(commands, "get_settings", get_settings),
patch.object(commands.uvicorn, "Config", side_effect=fake_config),
- patch.object(commands.uvicorn, "Server", side_effect=FakeServer),
+ patch.object(commands, "RuntimeServer", side_effect=FakeServer),
patch.object(commands, "build_asgi_app", side_effect=build_asgi_app),
patch.object(commands, "schedule_open_admin_browser") as schedule_open_admin,
patch.object(commands, "clear_settings_cache") as clear_settings_cache,
@@ -379,10 +381,12 @@ def test_serve_supervisor_refuses_restart_after_incomplete_shutdown() -> None:
def build_asgi_app(_settings: Settings, restart_callback: Callable[[], None]):
restart_callbacks.append(restart_callback)
- return SimpleNamespace(runtime=SimpleNamespace(is_closed=False))
+ return SimpleNamespace(
+ runtime=SimpleNamespace(is_closed=False, begin_shutdown=lambda: None)
+ )
class FakeServer:
- def __init__(self, config):
+ def __init__(self, config, *, begin_shutdown):
self.config = config
self.should_exit = False
servers.append(self)
@@ -397,7 +401,7 @@ def test_serve_supervisor_refuses_restart_after_incomplete_shutdown() -> None:
with (
patch.object(commands, "get_settings", get_settings),
patch.object(commands.uvicorn, "Config", side_effect=fake_config),
- patch.object(commands.uvicorn, "Server", side_effect=FakeServer),
+ patch.object(commands, "RuntimeServer", side_effect=FakeServer),
patch.object(commands, "build_asgi_app", side_effect=build_asgi_app),
patch.object(commands, "schedule_open_admin_browser"),
patch.object(commands, "clear_settings_cache") as clear_settings_cache,
diff --git a/tests/cli/test_server_shutdown.py b/tests/cli/test_server_shutdown.py
new file mode 100644
index 00000000..92ffbef1
--- /dev/null
+++ b/tests/cli/test_server_shutdown.py
@@ -0,0 +1,114 @@
+"""Exercise supervised shutdown with real HTTP event-feed connections."""
+
+import asyncio
+import socket
+import threading
+from pathlib import Path
+from unittest.mock import AsyncMock
+
+import httpx
+import pytest
+
+from free_claude_code.cli import commands
+from free_claude_code.config.settings import Settings
+from free_claude_code.runtime.application import RestartCallback
+from free_claude_code.runtime.asgi import RuntimeASGIApp
+from free_claude_code.runtime.bootstrap import build_asgi_app
+
+
[email protected]("restart", [False, True])
+async def test_supervisor_drains_admin_event_feed_without_forced_cancellation(
+ monkeypatch: pytest.MonkeyPatch,
+ tmp_path: Path,
+ caplog: pytest.LogCaptureFixture,
+ restart: bool,
+) -> None:
+ with socket.socket() as listener:
+ listener.bind(("127.0.0.1", 0))
+ port = listener.getsockname()[1]
+ settings = Settings().model_copy(
+ update={
+ "host": "127.0.0.1",
+ "port": port,
+ "messaging_platform": "none",
+ "voice_note_enabled": False,
+ "open_admin_browser": False,
+ "log_file": str(tmp_path / "server.log"),
+ }
+ )
+ apps: list[RuntimeASGIApp] = []
+
+ def create_app(settings: Settings, *, restart_callback: RestartCallback):
+ app = build_asgi_app(settings, restart_callback=restart_callback)
+ # Only provider discovery is external; retain the real Chat, HTTP,
+ # runtime cleanup, and supervisor lifecycle under investigation.
+ monkeypatch.setattr(
+ app.runtime.provider_manager, "warm_referenced_model_cache", AsyncMock()
+ )
+ monkeypatch.setattr(
+ app.runtime.provider_manager, "start_model_list_refresh", lambda: None
+ )
+ apps.append(app)
+ return app
+
+ monkeypatch.setattr(commands, "load_server_settings", lambda: settings)
+ monkeypatch.setattr(
+ "free_claude_code.runtime.bootstrap.configure_logging",
+ lambda *args, **kwargs: None,
+ )
+ monkeypatch.setattr(commands, "build_asgi_app", create_app)
+ monkeypatch.setattr(commands, "kill_all_best_effort", lambda: None)
+ monkeypatch.setattr(commands, "SERVER_GRACEFUL_SHUTDOWN_SECONDS", 0.2)
+ supervisor = commands.ServerSupervisor(console_logging=False)
+ thread = threading.Thread(target=supervisor.run, daemon=True)
+ thread.start()
+ stream_error: Exception | None = None
+ try:
+ async with asyncio.timeout(5):
+ while supervisor.status != commands.ServerStatus.RUNNING:
+ assert thread.is_alive()
+ await asyncio.sleep(0.01)
+ async with httpx.AsyncClient(timeout=3, trust_env=False) as client:
+ status_url = f"http://127.0.0.1:{port}/admin/api/status"
+ old_instance = (await client.get(status_url)).json()["instance_id"]
+ events_url = f"http://127.0.0.1:{port}/admin/api/chat/events"
+ async with (
+ client.stream("GET", events_url) as first,
+ client.stream("GET", events_url) as second,
+ ):
+ streams = [first.aiter_lines(), second.aiter_lines()]
+ assert first.status_code == second.status_code == 200
+ for lines in streams:
+ async for line in lines:
+ if line.startswith("event: feed.ready"):
+ break
+ if restart:
+ assert supervisor.request_restart()
+ else:
+ supervisor.request_stop()
+ for lines in streams:
+ try:
+ async for _line in lines:
+ pass
+ except httpx.HTTPError as exc:
+ stream_error = exc
+ if restart:
+ async with asyncio.timeout(5):
+ while (
+ len(apps) < 2
+ or supervisor.status != commands.ServerStatus.RUNNING
+ ):
+ assert thread.is_alive()
+ await asyncio.sleep(0.01)
+ new_status = (await client.get(status_url)).json()
+ assert new_status["status"] == "running"
+ assert new_status["instance_id"] != old_instance
+ finally:
+ supervisor.request_stop()
+ await asyncio.to_thread(thread.join, 5)
+ assert not thread.is_alive()
+ assert stream_error is None, f"Event feed was cut off: {stream_error}"
+ assert "timeout graceful shutdown exceeded" not in caplog.text
+ assert all(app.runtime.is_closed for app in apps)
+ assert len(apps) == (2 if restart else 1)
diff --git a/tests/runtime/test_application_runtime.py b/tests/runtime/test_application_runtime.py
index 96b21a40..ab3c09ba 100644
--- a/tests/runtime/test_application_runtime.py
+++ b/tests/runtime/test_application_runtime.py
@@ -472,6 +472,7 @@ async def test_restart_required_apply_commits_without_hot_publication(tmp_path)
tmp_path,
pending_fields=("PORT",),
)
+ instance_id = runtime.admin_status()["instance_id"]
with (
patch(
@@ -493,6 +494,7 @@ async def test_restart_required_apply_commits_without_hot_publication(tmp_path)
"automatic": True,
"admin_url": "http://127.0.0.1:9090/admin",
"fields": ["PORT"],
+ "instance_id": instance_id,
}
restart.assert_not_awaited()
await runtime.request_restart()
diff --git a/uv.lock b/uv.lock
index 3758cfa3..543db0e8 100644
--- a/uv.lock
+++ b/uv.lock
@@ -598,7 +598,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "5.21.0"
+version = "5.21.1"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },