π The fast, Pythonic way to build MCP servers and clients.
Keep task routing keys alive via sliding TTL; version-aware worker server resolution
Jeremiah Lowin53741dc9c7d8
diff --git a/fastmcp_tasks/fastmcp_tasks/context.py b/fastmcp_tasks/fastmcp_tasks/context.pyindex 22bdf0259..8a9c421b7 100644--- a/fastmcp_tasks/fastmcp_tasks/context.py+++ b/fastmcp_tasks/fastmcp_tasks/context.py@@ -145,15 +145,22 @@ class TaskContextSnapshot:origin_request_id: str | None = Nonesession_id: str | None = Noneowning_tool_name: str | None = None+ owning_tool_version: str | None = None@classmethod- def capture(cls, owning_tool_name: str | None = None) -> TaskContextSnapshot:+ def capture(+ cls,+ owning_tool_name: str | None = None,+ owning_tool_version: str | None = None,+ ) -> TaskContextSnapshot:"""Capture current context for background task execution.- ``owning_tool_name`` is the routable name of the tool the call targeted.- A remote worker (separate process) cannot reach the submitting process's- server map, so it re-resolves the owning (child) server from this name- against the root β see ``make_task_context``.+ ``owning_tool_name``/``owning_tool_version`` identify the exact tool the+ call targeted. A remote worker (separate process) cannot reach the+ submitting process's server map, so it re-resolves the owning (child)+ server from this name and version against the root β see+ ``make_task_context``. The version matters when two versions of the same+ mounted tool name live on different child servers."""from fastmcp.server.dependencies import (get_access_token,@@ -178,6 +185,7 @@ class TaskContextSnapshot:),session_id=session_id,owning_tool_name=owning_tool_name,+ owning_tool_version=owning_tool_version,)@classmethod@@ -195,6 +203,7 @@ class TaskContextSnapshot:origin_request_id=parsed.get("origin_request_id"),session_id=parsed.get("session_id"),owning_tool_name=parsed.get("owning_tool_name"),+ owning_tool_version=parsed.get("owning_tool_version"),)def to_json(self) -> str:@@ -206,6 +215,7 @@ class TaskContextSnapshot:"origin_request_id": self.origin_request_id,"session_id": self.session_id,"owning_tool_name": self.owning_tool_name,+ "owning_tool_version": self.owning_tool_version,})@@ -435,10 +445,19 @@ async def _resolve_owning_server(from fastmcp.exceptions import NotFoundErrorfrom fastmcp.server.dependencies import get_serverfrom fastmcp.server.providers.fastmcp_provider import FastMCPProviderTool+ from fastmcp.utilities.versions import VersionSpecroot = get_server()+ # Resolve the exact version the call targeted: two versions of the same+ # mounted tool name can live on different child servers, so omitting the+ # version could pick the wrong server's state and masking policy.+ version = (+ VersionSpec(eq=snapshot.owning_tool_version)+ if snapshot.owning_tool_version+ else None+ )try:- tool = await root.get_tool(snapshot.owning_tool_name)+ tool = await root.get_tool(snapshot.owning_tool_name, version)except NotFoundError:return Noneif isinstance(tool, FastMCPProviderTool):diff --git a/fastmcp_tasks/fastmcp_tasks/creation.py b/fastmcp_tasks/fastmcp_tasks/creation.pyindex 745e7ceb7..7fc65ead9 100644--- a/fastmcp_tasks/fastmcp_tasks/creation.py+++ b/fastmcp_tasks/fastmcp_tasks/creation.py@@ -109,7 +109,9 @@ async def create_task(created_at_key = docket.key(f"{prefix}:{task_id}:created_at")poll_interval_key = docket.key(f"{prefix}:{task_id}:poll_interval")- snapshot = TaskContextSnapshot.capture(owning_tool_name=tool.name)+ snapshot = TaskContextSnapshot.capture(+ owning_tool_name=tool.name, owning_tool_version=tool.version+ )async with docket.redis() as redis:await redis.set(task_meta_key, task_key, ex=ttl_seconds)diff --git a/fastmcp_tasks/fastmcp_tasks/handlers.py b/fastmcp_tasks/fastmcp_tasks/handlers.pyindex a4f7b0800..b12aabf19 100644--- a/fastmcp_tasks/fastmcp_tasks/handlers.py+++ b/fastmcp_tasks/fastmcp_tasks/handlers.py@@ -33,7 +33,11 @@ from fastmcp.tools.base import InputRequiredToolResult, Tool, ToolResultfrom fastmcp.utilities.tasks import DEFAULT_POLL_INTERVAL_MSfrom fastmcp.utilities.versions import VersionSpecfrom fastmcp_tasks.context import get_task_scope-from fastmcp_tasks.creation import enqueue_task_leg, registered_component_for_key+from fastmcp_tasks.creation import (+ TASK_MAPPING_TTL_BUFFER_SECONDS,+ enqueue_task_leg,+ registered_component_for_key,+)from fastmcp_tasks.input_store import (acquire_update_lock,acquire_update_lock_blocking,@@ -43,6 +47,7 @@ from fastmcp_tasks.input_store import (load_task_args,mark_cancelled,read_outstanding_inputs,+ refresh_current_leg_ttl,release_update_lock,save_current_leg,store_input_responses,@@ -108,6 +113,16 @@ def _ttl_ms(docket: Docket) -> int:return int(docket.execution_ttl.total_seconds() * 1000)+def _task_key_ttl_seconds(docket: Docket) -> int:+ """Wall-clock TTL for a task's Redis metadata keys.++ Docket's ``execution_ttl`` plus a buffer (matching task creation), so a key+ written or refreshed now comfortably outlives the execution-retention+ window. Sliding expiration on each poll keeps it alive for long legs.+ """+ return int(docket.execution_ttl.total_seconds()) + TASK_MAPPING_TTL_BUFFER_SECONDS++async def _lookup_task(docket: Docket, task_scope: str | None, task_id: str) -> tuple[Any, str, int, str | None, int]:@@ -141,6 +156,16 @@ async def _lookup_task(if not execution:raise _task_not_found(task_id)+ # Sliding expiration: an actively-polled task refreshes its routing keys so+ # they never expire mid-execution β a resumed leg that runs longer than the+ # keys' wall-clock TTL would otherwise strand `_lookup_task` on the base leg.+ refresh_ttl = _task_key_ttl_seconds(docket)+ async with docket.redis() as redis:+ await redis.expire(meta_key, refresh_ttl)+ await redis.expire(created_at_key, refresh_ttl)+ await redis.expire(poll_key, refresh_ttl)+ await refresh_current_leg_ttl(docket, task_scope, task_id, refresh_ttl)+created_at = created_at_bytes.decode("utf-8") if created_at_bytes else Nonetry:@@ -350,9 +375,13 @@ async def tasks_update(next_leg_key = leg_execution_key(base_task_key, next_leg)await enqueue_task_leg(server, docket, component, raw_arguments, next_leg_key)- ttl_seconds = int(docket.execution_ttl.total_seconds())await save_current_leg(- docket, task_scope, task_id, next_leg_key, next_leg, ttl_seconds+ docket,+ task_scope,+ task_id,+ next_leg_key,+ next_leg,+ _task_key_ttl_seconds(docket),)# The answered leg's surfaced keys are now superseded; drop them so they# are never reused (SEP-2663 L350).diff --git a/fastmcp_tasks/fastmcp_tasks/input_store.py b/fastmcp_tasks/fastmcp_tasks/input_store.pyindex edd46ef64..d13a6e82e 100644--- a/fastmcp_tasks/fastmcp_tasks/input_store.py+++ b/fastmcp_tasks/fastmcp_tasks/input_store.py@@ -184,6 +184,22 @@ async def save_current_leg()+async def refresh_current_leg_ttl(+ docket: Docket, task_scope: str | None, task_id: str, ttl_seconds: int+) -> None:+ """Extend the current-leg pointer's TTL (sliding expiration).++ The pointer is written with a wall-clock TTL, but a leg's execution can run+ longer than that β a resumed guard leg especially. Refreshing on each poll+ keeps the routing pointer alive for an actively-polled task no matter how+ long the leg runs, so ``_lookup_task`` never falls back to the base leg+ while the current leg is still executing.+ """+ async with docket.redis() as redis:+ await redis.expire(_current_leg_key(docket, task_scope, task_id), ttl_seconds)+ await redis.expire(_leg_number_key(docket, task_scope, task_id), ttl_seconds)++async def load_current_leg(docket: Docket, task_scope: str | None, task_id: str) -> tuple[str | None, int]:diff --git a/tests/tasks/server/test_task_mount.py b/tests/tasks/server/test_task_mount.pyindex c13836247..df8f23deb 100644--- a/tests/tasks/server/test_task_mount.py+++ b/tests/tasks/server/test_task_mount.py@@ -167,6 +167,47 @@ class TestRemoteWorkerServerResolution:finally:_current_server.reset(token)+ async def test_resolve_owning_server_respects_version(self):+ """Two versions of a mounted tool name resolve to their own child server."""+ import weakref++ from fastmcp_tasks.context import (+ TaskContextSnapshot,+ _resolve_owning_server,+ )++ from fastmcp.server.dependencies import _current_server++ child_v1 = FastMCP("child-v1")++ @child_v1.tool(name="calc", version="1.0", task=True)+ async def calc_v1() -> str:+ return "v1"++ child_v2 = FastMCP("child-v2")++ @child_v2.tool(name="calc", version="2.0", task=True)+ async def calc_v2() -> str:+ return "v2"++ parent = FastMCP("parent-versions")+ parent.add_extension(TasksExtension())+ parent.mount(child_v1)+ parent.mount(child_v2)++ token = _current_server.set(weakref.ref(parent))+ try:+ resolved_v1 = await _resolve_owning_server(+ TaskContextSnapshot(owning_tool_name="calc", owning_tool_version="1.0")+ )+ resolved_v2 = await _resolve_owning_server(+ TaskContextSnapshot(owning_tool_name="calc", owning_tool_version="2.0")+ )+ assert resolved_v1 is child_v1+ assert resolved_v2 is child_v2+ finally:+ _current_server.reset(token)+class TestMountedToolTasksNoPrefix:async def test_mounted_tool_without_prefix_works(self, child_server):diff --git a/tests/tasks/server/test_task_ttl.py b/tests/tasks/server/test_task_ttl.pyindex a3bb74b2d..8fa9f670e 100644--- a/tests/tasks/server/test_task_ttl.py+++ b/tests/tasks/server/test_task_ttl.py@@ -69,3 +69,30 @@ async def test_default_ttl_when_unspecified():assert created.ttl_ms == DEFAULT_TTL_MSgot = await get_task(mcp, created.task_id)assert got.ttl_ms == DEFAULT_TTL_MS+++async def test_poll_refreshes_routing_key_ttl():+ """A poll extends the current-leg pointer's TTL (sliding expiration).++ A leg that runs longer than the pointer's wall-clock TTL would otherwise+ strand `_lookup_task` on the base leg. Polling must keep the routing keys+ alive: after shrinking the pointer's TTL, a `tasks/get` restores it.+ """+ from fastmcp_tasks.input_store import _current_leg_key++ mcp = _ttl_server()+ async with running_task_server(mcp):+ created = await submit_task(mcp, "slow_task", {})+ docket = mcp._docket+ assert docket is not None+ key = _current_leg_key(docket, None, created.task_id)++ async with docket.redis() as redis:+ await redis.expire(key, 5)+ assert await redis.ttl(key) <= 5++ await get_task(mcp, created.task_id)++ async with docket.redis() as redis:+ # Refreshed well past the shrunk 5s, back toward the full window.+ assert await redis.ttl(key) > 60