Skip to content

Commit b974bc1

Browse files
authored
Python: report an over-long Windows path as ENAMETOOLONG, not a missing file (microsoft#10202)
* Python: report an over-long Windows path as ENAMETOOLONG, not a missing file On Windows without long-path support, FileSystemAgentFileStore.write() reported a path that merely exceeded the OS limit as FileNotFoundError, which reads as a missing file and sends callers looking for a bug in their own path handling. The limit is now used only to explain an error the OS already raised: when write() fails and a prefix of the path that is still inside the limit exists, the failure is re-raised as OSError(errno.ENAMETOOLONG), chained to the original error. Paths are never rejected up front, so a host with long-path support keeps its current behaviour and every in-limit path is untouched. Directories use the 248-character directory limit, files the 260-character one. The within-bound half of test_filesystem_store_matches_in_memory_complexity_bound now expects ENAMETOOLONG on a Windows host with long paths disabled. New tests cover both call sites with a pinned platform flag, check that unrelated FileNotFoundErrors still propagate unchanged, and check that a path past the limit is still written and read when the host supports long paths. Fixes microsoft#10141 * Python: address long-path review feedback Count Windows path limits in UTF-16 code units instead of Python code points, restrict the ENAMETOOLONG rewrite to FileNotFoundError so collisions and permission failures keep their own types, and size the regression test's file name from the temporary directory so the path always crosses MAX_PATH.
1 parent b193c1b commit b974bc1

2 files changed

Lines changed: 270 additions & 3 deletions

File tree

‎python/packages/core/agent_framework/_harness/_file_access.py‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
import fnmatch
2727
import logging
2828
import os
29+
import sys
2930
import threading
3031
import time
3132
import unicodedata
@@ -99,6 +100,19 @@
99100
_MAX_PATH_SEGMENTS: Final[int] = 255
100101
_MAX_PATH_LENGTH: Final[int] = 4096
101102

103+
# Windows path length limits, counted the way Windows counts them: in UTF-16 code
104+
# units, not Python code points (a supplementary character is two units). They are
105+
# consulted only to explain an error the OS already raised (see
106+
# :func:`_raise_if_path_too_long`); they never gate a path up front. ``MAX_PATH`` is
107+
# 260 of those units including the drive, the separators and the terminating NUL, and
108+
# ``CreateDirectory`` needs room for the 8.3 name it may have to synthesize, which is
109+
# where the 248-unit directory limit comes from.
110+
# https://learn.microsoft.com/windows/win32/fileio/maximum-file-path-limitation
111+
_WINDOWS_MAX_PATH_CHARS: Final[int] = 260
112+
_WINDOWS_MAX_DIRECTORY_PATH_CHARS: Final[int] = 248
113+
# Pinned in a constant so tests can exercise both branches on any platform.
114+
_WINDOWS_PATH_LIMITS_APPLY: Final[bool] = sys.platform == "win32"
115+
102116
# Hard cap on the length of a user-supplied search regex. The cap is a coarse bound on
103117
# how much work a single pattern can describe; it does not stop a short pathological
104118
# pattern, which is what :class:`_BoundedSearchPattern` is for.
@@ -1330,6 +1344,50 @@ async def create_directory(self, path: str) -> None:
13301344
self._explicit_dirs[key] = display
13311345

13321346

1347+
def _windows_path_length(path: Path) -> int:
1348+
"""Return the length Windows measures for *path*, in UTF-16 code units.
1349+
1350+
Windows path limits are expressed in UTF-16 code units, while ``len`` on a Python
1351+
string counts Unicode code points. A supplementary character such as an emoji is one
1352+
code point but two UTF-16 units, so counting code points would understate the path
1353+
and could miss a genuine length failure.
1354+
"""
1355+
return len(str(path).encode("utf-16-le", "surrogatepass")) // 2
1356+
1357+
1358+
def _raise_if_path_too_long(exc: OSError, path: Path, *, limit: int) -> None:
1359+
"""Re-raise an over-long Windows path failure as :data:`errno.ENAMETOOLONG`.
1360+
1361+
Without long-path support Windows reports a path past its limit as a missing path,
1362+
which CPython surfaces as :class:`FileNotFoundError`. Callers then go looking for a
1363+
bug in their own path handling instead of shortening the key.
1364+
1365+
Only that missing-path symptom is rewritten. A collision or a permission failure has
1366+
its own exception type and must keep it, even when the path happens to be over the
1367+
limit: with long-path support enabled Windows reports those directly, and relabeling
1368+
them as a length problem would hide the real cause.
1369+
1370+
The length is used only to explain an error that already happened. Nothing here
1371+
rejects a path before it is used, so a host with long-path support behaves exactly as
1372+
before and every in-limit path stays untouched. The rewrite additionally requires a
1373+
prefix inside the limit to exist; without one the path is missing for an ordinary
1374+
reason and the original error is the accurate one.
1375+
"""
1376+
if not _WINDOWS_PATH_LIMITS_APPLY or not isinstance(exc, FileNotFoundError):
1377+
return
1378+
if _windows_path_length(path) < limit:
1379+
return
1380+
prefix = path
1381+
while _windows_path_length(prefix) >= limit:
1382+
parent = prefix.parent
1383+
if parent == prefix:
1384+
return
1385+
prefix = parent
1386+
if not prefix.exists():
1387+
return
1388+
raise OSError(errno.ENAMETOOLONG, "File name too long", str(path)) from exc
1389+
1390+
13331391
@experimental(feature_id=ExperimentalFeature.HARNESS)
13341392
class FileSystemAgentFileStore(AgentFileStore):
13351393
"""A disk-backed :class:`AgentFileStore` rooted under a configurable directory.
@@ -1351,6 +1409,15 @@ class FileSystemAgentFileStore(AgentFileStore):
13511409
symlink between the probe and the file open. This store is designed for
13521410
single-tenant or co-operating-tenant use; it is not a sandbox against a
13531411
hostile process that shares the root directory.
1412+
1413+
On Windows the length of the resolved path (root plus key) is limited to 260 UTF-16
1414+
code units for a file and 248 for a directory unless long-path support is enabled
1415+
(``LongPathsEnabled``). :meth:`write` reports that limit as :class:`OSError` with
1416+
:data:`errno.ENAMETOOLONG` instead of the ``FileNotFoundError`` the OS raises, so a
1417+
caller can tell "too long" apart from "missing". The limit only renames a failure
1418+
the OS already produced; paths are never rejected up front, and a host with
1419+
long-path support behaves exactly as before. :class:`InMemoryAgentFileStore` has no
1420+
such limit, so the two backends still differ at that bound.
13541421
"""
13551422

13561423
# Case aliases can identify the same file while having different Path hashes.
@@ -1502,6 +1569,11 @@ def _write_file_sync(full_path: Path, content: str, overwrite: bool) -> None:
15021569
if parent_file is not None:
15031570
raise NotADirectoryError(f"Parent path is not a directory: {parent_file}") from exc
15041571
raise
1572+
except OSError as exc:
1573+
# Windows reports an over-long absolute path as FileNotFoundError; name the
1574+
# real cause before the caller reads it as a missing parent directory.
1575+
_raise_if_path_too_long(exc, full_path.parent, limit=_WINDOWS_MAX_DIRECTORY_PATH_CHARS)
1576+
raise
15051577
encoded = content.encode("utf-8")
15061578
flags = os.O_WRONLY | os.O_CREAT
15071579
if overwrite:
@@ -1516,6 +1588,7 @@ def _write_file_sync(full_path: Path, content: str, overwrite: bool) -> None:
15161588
try:
15171589
fd = os.open(full_path, flags, 0o644)
15181590
except OSError as exc:
1591+
_raise_if_path_too_long(exc, full_path, limit=_WINDOWS_MAX_PATH_CHARS)
15191592
# Windows reports PermissionError when opening a directory for
15201593
# writing; POSIX exclusive creation can report FileExistsError.
15211594
if isinstance(exc, (FileExistsError, PermissionError)) and full_path.is_dir():

‎python/packages/core/tests/core/test_harness_file_access.py‎

Lines changed: 197 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
import os
99
import re
1010
import stat
11+
import sys
1112
import threading
1213
import time
1314
from contextlib import suppress
@@ -2983,9 +2984,33 @@ async def test_in_memory_store_accepts_deep_paths_within_the_bound() -> None:
29832984
assert retained < 200 * len(path)
29842985

29852986

2987+
def _windows_long_paths_disabled() -> bool:
2988+
"""Return whether this host is Windows with long-path support turned off.
2989+
2990+
Read-only: the registry value is queried, never written. The Windows default is
2991+
``0`` when the value or key is absent. The concept does not apply elsewhere, so
2992+
this returns ``False`` on every other platform.
2993+
"""
2994+
if sys.platform != "win32":
2995+
return False
2996+
try:
2997+
import winreg
2998+
2999+
with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, r"SYSTEM\CurrentControlSet\Control\FileSystem") as key:
3000+
enabled, _ = winreg.QueryValueEx(key, "LongPathsEnabled")
3001+
except OSError:
3002+
return True
3003+
return not enabled
3004+
3005+
29863006
async def test_filesystem_store_matches_in_memory_complexity_bound(tmp_path) -> None:
29873007
"""Both backends refuse the same over-bound path with the same errno, so
2988-
backend substitution is not observable on the bound either."""
3008+
backend substitution is not observable on the bound either.
3009+
3010+
That agreement stops at the OS bound. On Windows without long-path support a
3011+
200-segment key is still legal for the store itself but not for the filesystem,
3012+
so the within-bound half expects the normalized ``ENAMETOOLONG`` there.
3013+
"""
29893014
import errno
29903015

29913016
fs_store = FileSystemAgentFileStore(str(tmp_path))
@@ -3001,7 +3026,176 @@ async def test_filesystem_store_matches_in_memory_complexity_bound(tmp_path) ->
30013026
assert mem_info.value.errno == errno.ENAMETOOLONG
30023027

30033028
within = "/".join(["d"] * 200 + ["f"])
3004-
await fs_store.write(within, "x")
30053029
await mem_store.write(within, "x")
3006-
assert await fs_store.read(within) == "x"
30073030
assert await mem_store.read(within) == "x"
3031+
3032+
if _windows_long_paths_disabled():
3033+
with pytest.raises(OSError) as within_info:
3034+
await fs_store.write(within, "x")
3035+
assert within_info.value.errno == errno.ENAMETOOLONG
3036+
# The path is not reachable for the filesystem backend, so it reads as absent.
3037+
assert await fs_store.read(within) is None
3038+
else:
3039+
await fs_store.write(within, "x")
3040+
assert await fs_store.read(within) == "x"
3041+
3042+
3043+
@pytest.mark.parametrize("failure_point", ["mkdir", "open"])
3044+
async def test_filesystem_store_normalizes_windows_path_too_long_error(
3045+
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, failure_point: str
3046+
) -> None:
3047+
"""An OS "path too long" failure is reported as ``ENAMETOOLONG``.
3048+
3049+
Windows reports an absolute path past its limit as a missing path, which CPython
3050+
surfaces as ``FileNotFoundError``; without the rewrite the store reports a path that
3051+
is merely too long as a missing file. The failure is injected at both points where
3052+
the store touches the OS and the platform flag is pinned, so the test also runs on
3053+
CI hosts that have long paths enabled.
3054+
"""
3055+
import errno
3056+
3057+
monkeypatch.setattr("agent_framework._harness._file_access._WINDOWS_PATH_LIMITS_APPLY", True)
3058+
store = FileSystemAgentFileStore(str(tmp_path))
3059+
too_long = FileNotFoundError(errno.ENOENT, "The system cannot find the path specified", "too-long")
3060+
3061+
def raise_too_long(*_args: object, **_kwargs: object) -> None:
3062+
raise too_long
3063+
3064+
if failure_point == "mkdir":
3065+
# A directory past its limit is what a real host refuses, and it still creates the
3066+
# prefixes below the limit first; the rewrite checks for one of those.
3067+
real_mkdir = Path.mkdir
3068+
key = "/".join(["d" * 40] * 8) # absolute path well past both limits
3069+
3070+
def length_aware_mkdir(self: Path, mode: int = 0o777, parents: bool = False, exist_ok: bool = False) -> None:
3071+
if len(str(self)) >= 248:
3072+
# Mimic pathlib's recursion: create the deepest prefix that is still legal,
3073+
# then refuse, exactly as the OS does.
3074+
prefix = self
3075+
while len(str(prefix)) >= 248 and prefix.parent != prefix:
3076+
prefix = prefix.parent
3077+
if prefix != self and len(str(prefix)) < 248:
3078+
real_mkdir(prefix, parents=True, exist_ok=True)
3079+
raise_too_long()
3080+
real_mkdir(self, mode, parents, exist_ok)
3081+
3082+
monkeypatch.setattr(Path, "mkdir", length_aware_mkdir)
3083+
else:
3084+
# Grow the parent until it is just inside the directory limit, then size the file
3085+
# name from the current length so the absolute path is guaranteed to reach the
3086+
# file limit wherever ``tmp_path`` happens to live.
3087+
segments: list[str] = []
3088+
current = len(str(tmp_path))
3089+
while current + 1 + 34 <= 247:
3090+
segments.append("d" * 34)
3091+
current += 1 + 34
3092+
key = "/".join([*segments, "f" * max(1, 260 - current - 1)])
3093+
monkeypatch.setattr(os, "open", raise_too_long)
3094+
3095+
with pytest.raises(OSError) as exc_info:
3096+
await store.write(key, "x")
3097+
3098+
assert not isinstance(exc_info.value, FileNotFoundError)
3099+
assert exc_info.value.errno == errno.ENAMETOOLONG
3100+
assert exc_info.value.__cause__ is too_long
3101+
3102+
3103+
@pytest.mark.skipif(_windows_long_paths_disabled(), reason="this host rejects paths past MAX_PATH")
3104+
async def test_filesystem_store_never_rejects_a_path_past_the_windows_limit(tmp_path: Path) -> None:
3105+
"""The Windows limits only rename a failure; they never reject a path up front.
3106+
3107+
On a host that supports long paths, the key that fails on a legacy host must still be
3108+
written and read. A length check applied before the OS call would break exactly this
3109+
case, which is why the rewrite runs only inside an ``except`` block.
3110+
"""
3111+
store = FileSystemAgentFileStore(str(tmp_path))
3112+
key = "/".join(["d" * 40] * 8)
3113+
await store.write(key, "payload")
3114+
assert await store.read(key) == "payload"
3115+
3116+
3117+
async def test_filesystem_store_propagates_other_file_not_found_errors(
3118+
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
3119+
) -> None:
3120+
"""A ``FileNotFoundError`` that is not the Windows over-long-path error keeps
3121+
its type and identity, so a genuinely missing parent still reads as missing."""
3122+
import errno
3123+
3124+
store = FileSystemAgentFileStore(str(tmp_path))
3125+
missing = FileNotFoundError(errno.ENOENT, "The system cannot find the path specified")
3126+
3127+
def raise_missing(*_args: object, **_kwargs: object) -> None:
3128+
raise missing
3129+
3130+
monkeypatch.setattr(Path, "mkdir", raise_missing)
3131+
3132+
with pytest.raises(FileNotFoundError) as exc_info:
3133+
await store.write("nested/file.txt", "x")
3134+
3135+
assert exc_info.value is missing
3136+
3137+
3138+
async def test_filesystem_store_measures_long_paths_in_utf16_code_units(
3139+
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
3140+
) -> None:
3141+
"""The Windows limit is compared in UTF-16 code units, not Python code points.
3142+
3143+
A supplementary character such as an emoji is one code point but two UTF-16 units.
3144+
A path one code point short of 260 can therefore already have reached the Windows
3145+
limit, and must still be reported as too long.
3146+
"""
3147+
import errno
3148+
3149+
monkeypatch.setattr("agent_framework._harness._file_access._WINDOWS_PATH_LIMITS_APPLY", True)
3150+
store = FileSystemAgentFileStore(str(tmp_path))
3151+
root = str(store.root_path)
3152+
key = "f" * (257 - len(root)) + "\U0001f600"
3153+
target = store.root_path / key
3154+
# 259 code points, 260 UTF-16 units: only the Windows length has reached the limit.
3155+
assert len(str(target)) == 259
3156+
assert len(str(target).encode("utf-16-le")) // 2 == 260
3157+
3158+
too_long = FileNotFoundError(errno.ENOENT, "The system cannot find the path specified")
3159+
3160+
def raise_too_long(*_args: object, **_kwargs: object) -> None:
3161+
raise too_long
3162+
3163+
monkeypatch.setattr(os, "open", raise_too_long)
3164+
3165+
with pytest.raises(OSError) as exc_info:
3166+
await store.write(key, "x")
3167+
3168+
assert not isinstance(exc_info.value, FileNotFoundError)
3169+
assert exc_info.value.errno == errno.ENAMETOOLONG
3170+
assert exc_info.value.__cause__ is too_long
3171+
3172+
3173+
@pytest.mark.parametrize("error_type", [FileExistsError, PermissionError])
3174+
async def test_filesystem_store_preserves_non_missing_errors_on_long_paths(
3175+
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, error_type: type[OSError]
3176+
) -> None:
3177+
"""Collisions and permission failures on an over-long path keep their own type.
3178+
3179+
Only the legacy "missing path" symptom is rewritten. With long-path support enabled
3180+
Windows reports an existing file as ``FileExistsError`` and a refusal as
3181+
``PermissionError``; relabeling either as a length problem would hide the real cause.
3182+
"""
3183+
import errno
3184+
3185+
monkeypatch.setattr("agent_framework._harness._file_access._WINDOWS_PATH_LIMITS_APPLY", True)
3186+
store = FileSystemAgentFileStore(str(tmp_path))
3187+
key = "f" * (260 - len(str(store.root_path)) - 1)
3188+
error_number = errno.EEXIST if error_type is FileExistsError else errno.EACCES
3189+
error = error_type(error_number, "original failure")
3190+
assert len(str(store.root_path / key)) == 260
3191+
3192+
def raise_error(*_args: object, **_kwargs: object) -> None:
3193+
raise error
3194+
3195+
monkeypatch.setattr(os, "open", raise_error)
3196+
3197+
with pytest.raises(OSError) as exc_info:
3198+
await store.write(key, "x")
3199+
3200+
assert exc_info.value is error
3201+
assert exc_info.value.errno == error_number

0 commit comments

Comments
 (0)