π The fast, Pythonic way to build MCP servers and clients.
fix: FileSystemProvider reload race condition (#3938)
Bill Easton5593cf3e117b
diff --git a/src/fastmcp/server/providers/filesystem.py b/src/fastmcp/server/providers/filesystem.pyindex 774021dca..6c6927239 100644--- a/src/fastmcp/server/providers/filesystem.py+++ b/src/fastmcp/server/providers/filesystem.py@@ -28,8 +28,9 @@ Example:from __future__ import annotationsimport asyncio-from collections.abc import Sequence+from collections.abc import Callable, Sequencefrom pathlib import Path+from typing import Anyfrom fastmcp.prompts.base import Promptfrom fastmcp.resources.base import Resource@@ -96,16 +97,20 @@ class FileSystemProvider(LocalProvider):self._warned_files: dict[Path, float] = {}# Lock for serializing reload operations (created lazily)self._reload_lock: asyncio.Lock | None = None+ # Generation counter to deduplicate concurrent reloads+ self._reload_generation: int = 0# Always load once at init to catch errors earlyself._load_components()def _load_components(self) -> None:"""Discover and register all components from the filesystem."""- # Clear existing components if reloadingif self._loaded:self._components.clear()+ if not self._root.exists():+ logger.warning("FileSystemProvider root does not exist: %s", self._root)+result = discover_and_import(self._root)# Log warnings for failed files (only once per file version)@@ -154,73 +159,67 @@ class FileSystemProvider(LocalProvider):else:logger.debug("Ignoring unknown component type: %r", type(component))- async def _ensure_loaded(self) -> None:- """Ensure components are loaded, reloading if in reload mode.+ async def _with_reload(self, coro_fn: Callable[..., Any], *args: Any) -> Any:+ """Acquire the reload lock, reload if needed, then run *coro_fn*.++ Holding the lock across both the reload and the read prevents+ concurrent readers from seeing a partially-rebuilt ``_components``+ dict (the ``clear()`` + re-register window).- Uses a lock to serialize concurrent reload operations and runs- filesystem I/O off the event loop using asyncio.to_thread.+ A generation counter deduplicates concurrent reload requests:+ if another caller already reloaded while we waited for the lock,+ we skip the redundant reload."""if not self._reload and self._loaded:- return+ return await coro_fn(*args)# Create lock lazily (can't create in __init__ without event loop)if self._reload_lock is None:self._reload_lock = asyncio.Lock()+ generation_before = self._reload_generation+async with self._reload_lock:- # Double-check after acquiring lock- if self._reload or not self._loaded:+ if not self._loaded or (+ self._reload and self._reload_generation == generation_before+ ):await asyncio.to_thread(self._load_components)+ self._reload_generation += 1+ return await coro_fn(*args)# Override provider methods to support reload modeasync def _list_tools(self) -> Sequence[Tool]:- """Return all tools, reloading if in reload mode."""- await self._ensure_loaded()- return await super()._list_tools()+ return await self._with_reload(super()._list_tools)async def _get_tool(self, name: str, version: VersionSpec | None = None) -> Tool | None:- """Get a tool by name, reloading if in reload mode."""- await self._ensure_loaded()- return await super()._get_tool(name, version)+ return await self._with_reload(super()._get_tool, name, version)async def _list_resources(self) -> Sequence[Resource]:- """Return all resources, reloading if in reload mode."""- await self._ensure_loaded()- return await super()._list_resources()+ return await self._with_reload(super()._list_resources)async def _get_resource(self, uri: str, version: VersionSpec | None = None) -> Resource | None:- """Get a resource by URI, reloading if in reload mode."""- await self._ensure_loaded()- return await super()._get_resource(uri, version)+ return await self._with_reload(super()._get_resource, uri, version)async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:- """Return all resource templates, reloading if in reload mode."""- await self._ensure_loaded()- return await super()._list_resource_templates()+ return await self._with_reload(super()._list_resource_templates)async def _get_resource_template(self, uri: str, version: VersionSpec | None = None) -> ResourceTemplate | None:- """Get a resource template, reloading if in reload mode."""- await self._ensure_loaded()- return await super()._get_resource_template(uri, version)+ return await self._with_reload(super()._get_resource_template, uri, version)async def _list_prompts(self) -> Sequence[Prompt]:- """Return all prompts, reloading if in reload mode."""- await self._ensure_loaded()- return await super()._list_prompts()+ return await self._with_reload(super()._list_prompts)async def _get_prompt(self, name: str, version: VersionSpec | None = None) -> Prompt | None:- """Get a prompt by name, reloading if in reload mode."""- await self._ensure_loaded()- return await super()._get_prompt(name, version)+ return await self._with_reload(super()._get_prompt, name, version)def __repr__(self) -> str:return f"FileSystemProvider(root={self._root!r}, reload={self._reload})"diff --git a/tests/fs/test_provider.py b/tests/fs/test_provider.pyindex 37184a815..cce887a28 100644--- a/tests/fs/test_provider.py+++ b/tests/fs/test_provider.py@@ -1,5 +1,6 @@"""Tests for FileSystemProvider."""+import asyncioimport timefrom pathlib import Path@@ -183,7 +184,7 @@ def original() -> str:assert provider._loadedassert len(provider._components) == 1- # Add another file - should be picked up on next _ensure_loaded+ # Add another file - should be picked up on next read(tmp_path / "tool2.py").write_text("""\from fastmcp.tools import tool@@ -194,9 +195,9 @@ def added() -> str:""")- # With reload=True, _ensure_loaded re-scans- await provider._ensure_loaded()- assert len(provider._components) == 2+ # With reload=True, reading triggers a re-scan+ tools = await provider._list_tools()+ assert len(tools) == 2async def test_warning_deduplication_same_file(self, tmp_path: Path, capsys):"""Warnings for the same broken file should not repeat."""@@ -211,7 +212,7 @@ def added() -> str:assert "WARNING" in captured.err and "Failed to import" in captured.err# Second load (same file, unchanged) - should NOT warn again- await provider._ensure_loaded()+ await provider._list_tools()captured = capsys.readouterr()assert "Failed to import" not in captured.err@@ -232,7 +233,7 @@ def added() -> str:bad_file.write_text("syntax error here !!!")# Next load - should warn again (file changed)- await provider._ensure_loaded()+ await provider._list_tools()captured = capsys.readouterr()# Check for warning indicator (rich may truncate long paths)assert "WARNING" in captured.err and "Failed to import" in captured.err@@ -262,7 +263,7 @@ def my_tool() -> str:)# Load again - should NOT warn, file is fixed- await provider._ensure_loaded()+ await provider._list_tools()captured = capsys.readouterr()assert "Failed to import" not in captured.errassert len(provider._components) == 1@@ -272,12 +273,50 @@ def my_tool() -> str:bad_file.write_text("1/0 # broken again")# Should warn again- await provider._ensure_loaded()+ await provider._list_tools()captured = capsys.readouterr()# Check for warning indicator (rich may truncate long paths)assert "WARNING" in captured.err and "Failed to import" in captured.err+class TestFileSystemProviderReloadRace:+ """Test that concurrent readers don't see empty components during reload."""++ async def test_concurrent_reader_never_sees_empty(self, tmp_path: Path):+ """A reader during reload should see either old or new components, never empty."""+ (tmp_path / "tool.py").write_text(+ """\+from fastmcp.tools import tool++@tool+def my_tool() -> str:+ return "hello"+"""+ )++ provider = FileSystemProvider(tmp_path, reload=True)+ assert len(await provider._list_tools()) == 1++ observed_empty = False++ async def reader():+ nonlocal observed_empty+ for _ in range(20):+ tools = await provider._list_tools()+ if len(tools) == 0:+ observed_empty = True+ await asyncio.sleep(0)++ async def reloader():+ for _ in range(5):+ provider._loaded = False+ await provider._list_tools() # triggers reload+ await asyncio.sleep(0)++ await asyncio.gather(reader(), reloader())+ assert not observed_empty, "Reader saw empty components during reload"++class TestFileSystemProviderIntegration:"""Integration tests with FastMCP server."""