Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
from __future__ import annotations
import ctypes
import errno
import fnmatch
import hashlib
import json
import logging
import mimetypes
import os
import re
import shutil
import stat
import sys
import tempfile
import threading
import time
import uuid
from dataclasses import dataclass
from pathlib import Path
from typing import Any, BinaryIO, Callable
from core.media_types import is_inline_safe_type
logger = logging.getLogger(__name__)
MAX_FILE_BYTES = 25 * 1024 * 1024
MAX_LIST_ENTRIES = 5000
DELETE_UNDO_TTL_SECONDS = 3600
DELETE_UNDO_MAX_ENTRIES = 32
DELETE_UNDO_ENTRY_SIZE_CAP_BYTES = 512 * 1024 * 1024
DELETE_UNDO_TOTAL_SIZE_CAP_BYTES = 2 * 1024 * 1024 * 1024
COPY_TOTAL_SIZE_CAP_BYTES = 2 * 1024 * 1024 * 1024
# Every audio/* and video/* type is inline-safe too (``core.media_types.is_inline_safe_type``).
INLINE_SAFE_CONTENT_TYPES = {
"image/png",
"image/jpeg",
"image/gif",
"image/webp",
"image/avif",
"image/bmp",
"image/x-icon",
"image/heic",
"image/heif",
"application/pdf",
"text/plain",
"text/markdown",
"text/csv",
"application/json",
}
# ``Range: bytes=<first>-<last>`` with bounded digits: a longer number is treated as malformed (full
# 200 body) rather than handed to int(). A comma never matches, so multi-range requests also fall back.
_BYTE_RANGE_RE = re.compile(r"^\s*bytes\s*=\s*(\d{0,20})\s*-\s*(\d{0,20})\s*$", re.IGNORECASE)
def parse_byte_range(header: str | None, size: int) -> tuple[int, int] | None:
"""Resolve a single ``Range: bytes=`` spec against ``size`` bytes into an inclusive span.
Returns ``None`` to serve the whole body (no header, multi-range, or malformed spec — RFC 9110
lets a server ignore those) and raises ``RangeNotSatisfiableError`` for a parsable range that
starts at or beyond the end of the file."""
match = _BYTE_RANGE_RE.match(header or "")
if not match or not (match.group(1) or match.group(2)):
return None
first, last = match.group(1), match.group(2)
if not first:
suffix = int(last)
if suffix == 0 or size == 0:
raise RangeNotSatisfiableError(size)
return max(size - suffix, 0), size - 1
start = int(first)
if last and int(last) < start:
return None
if start >= size:
raise RangeNotSatisfiableError(size)
return start, min(int(last), size - 1) if last else size - 1
_AT_FDCWD = -100
_RENAME_NOREPLACE = 1
_RENAME_NOREPLACE_FALLBACK_WARNED = False
_WRITE_LOCKS_MUTEX = threading.Lock()
_WRITE_LOCKS: dict[str, threading.Lock] = {}
_WRITE_TEMP_PREFIX = ".avibe-write-"
_UPLOAD_CHUNK_BYTES = 1024 * 1024
_COPY_CHUNK_BYTES = 1024 * 1024
_COPY_TEMP_PREFIX = ".avibe-copy-"
_NO_REPLACE_UNSUPPORTED_ERRNOS = {errno.ENOSYS, errno.EINVAL, errno.ENOTSUP, errno.EOPNOTSUPP}
_HARD_LINK_UNSUPPORTED_ERRNOS = {errno.EPERM, errno.EXDEV, errno.ENOTSUP, errno.EOPNOTSUPP}
_DELETE_UNDO_DIR_NAME = "files_undo"
_DELETE_UNDO_ENTRY_NAME = "entry"
_DELETE_UNDO_METADATA_NAME = "metadata.json"
_DELETE_UNDO_LOCK = threading.Lock()
_DELETE_UNDO_INITIALIZED = False
_DELETE_UNDO_EXPIRY_TIMER: threading.Timer | None = None
_DELETE_UNDO_EXPIRY_TIMER_DEADLINE: float | None = None
_DELETE_UNDO_EXPIRY_TIMER_ROOT: Path | None = None
_DELETE_UNDO_ENTRY_SIZE_CAP_ENV = "AVIBE_FILES_UNDO_SIZE_CAP_BYTES"
_DELETE_UNDO_TTL_ENV = "AVIBE_FILES_UNDO_TTL_SECONDS"
_DELETE_UNDO_MAX_ENTRIES_ENV = "AVIBE_FILES_UNDO_MAX_ENTRIES"
_DELETE_UNDO_TOTAL_SIZE_CAP_ENV = "AVIBE_FILES_UNDO_TOTAL_SIZE_CAP_BYTES"
_COPY_TOTAL_SIZE_CAP_ENV = "AVIBE_FILES_COPY_SIZE_CAP_BYTES"
class FileBrowserError(Exception):
def __init__(self, code: str, message: str, status_code: int = 400) -> None:
super().__init__(message)
self.code = code
self.message = message
self.status_code = status_code
class RangeNotSatisfiableError(FileBrowserError):
def __init__(self, size: int) -> None:
super().__init__("range_not_satisfiable", "Requested range not satisfiable", 416)
self.size = size
class NotFoundError(FileBrowserError):
def __init__(self, message: str = "Path not found") -> None:
super().__init__("not_found", message, 404)
class ConflictError(FileBrowserError):
def __init__(self, code: str, message: str) -> None:
super().__init__(code, message, 409)
@dataclass(frozen=True)
class FileContent:
path: Path
mime: str
disposition: str
data: bytes
size: int = 0
# Inclusive (start, end) when ``data`` is a byte-range slice of the ``size``-byte file.
byte_range: tuple[int, int] | None = None
@dataclass(frozen=True)
class DeleteUndoEntry:
token: str
directory: Path
entry_path: Path
metadata_path: Path
original_path: Path
parent_dev: int
parent_ino: int
deleted_at: float
size: int
def resolve_safe_path(raw: str) -> Path:
"""Expand and canonicalize one user-supplied absolute filesystem path."""
expanded = _expanded_absolute_path(raw)
try:
return expanded.resolve(strict=False)
except (OSError, RuntimeError, ValueError) as exc:
raise FileBrowserError("invalid_path", str(exc), 400) from exc
def _expanded_absolute_path(raw: str) -> Path:
if not isinstance(raw, str) or not raw.strip():
raise FileBrowserError("invalid_path", "Path is required", 400)
expanded = Path(os.path.expanduser(raw))
if not expanded.is_absolute():
raise FileBrowserError("invalid_path", "Path must be absolute", 400)
return expanded
def resolve_existing_directory(raw: str) -> Path:
"""Resolve an absolute path to an existing directory WITHOUT following a symlink on the
final component.
Same hardening family as the upload-destination check (``_resolve_upload_directory``) and
the list/write/rename mutations: expand ``~``, require absolute, canonicalize the PARENT
strictly, append the final component without following a symlink there, then require the
result to be a real directory. Raises ``FileBrowserError`` / ``NotFoundError`` on any
violation. Shared by the terminal service's "Open Terminal Here" start directory.
"""
resolve_safe_path(raw) # reject blank / relative / uncanonicalizable early
expanded = _expanded_absolute_path(raw)
if expanded.parent == expanded:
directory = expanded # a filesystem root is a valid, already-canonical directory
else:
if expanded.name in {"", ".", ".."} or _raw_final_component(raw) in {".", ".."}:
raise NotFoundError("Directory not found")
try:
parent = expanded.parent.resolve(strict=True)
except FileNotFoundError as exc:
raise NotFoundError("Directory not found") from exc
except (OSError, RuntimeError, ValueError) as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
directory = parent / expanded.name
try:
stat_result = directory.lstat()
except FileNotFoundError as exc:
raise NotFoundError("Directory not found") from exc
except PermissionError as exc:
raise FileBrowserError("permission_denied", "Permission denied", 403) from exc
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
if not stat.S_ISDIR(stat_result.st_mode):
raise FileBrowserError("not_dir", "Path is not a directory", 400)
return directory
def _resolve_existing_path(raw: str) -> Path:
resolved = resolve_safe_path(raw)
try:
return resolved.resolve(strict=True)
except FileNotFoundError as exc:
raise NotFoundError() from exc
except (OSError, RuntimeError, ValueError) as exc:
raise FileBrowserError("invalid_path", str(exc), 400) from exc
def _resolve_entry_path(raw: str) -> Path:
expanded = _expanded_absolute_path(raw)
if expanded.name in {"", ".", ".."} or _raw_final_component(raw) in {".", ".."}:
raise FileBrowserError("invalid_path", "Path must include a valid entry name", 400)
try:
parent = expanded.parent.resolve(strict=True)
except FileNotFoundError as exc:
raise NotFoundError("Parent directory not found") from exc
except (OSError, RuntimeError, ValueError) as exc:
raise FileBrowserError("invalid_path", str(exc), 400) from exc
return parent / expanded.name
def _raw_final_component(raw: str) -> str:
expanded_raw = os.path.expanduser(raw)
separators = os.sep
if os.altsep:
separators += os.altsep
stripped = expanded_raw.rstrip(separators)
if not stripped:
return ""
return os.path.basename(stripped)
def _resolve_existing_entry_path(raw: str) -> Path:
path = _resolve_entry_path(raw)
_stat_existing(path, follow_symlinks=False)
return path
def _exists_no_follow(path: Path) -> bool:
try:
path.lstat()
return True
except FileNotFoundError:
return False
def _same_entry_no_follow(left: Path, right: Path) -> bool:
try:
left_stat = left.lstat()
right_stat = right.lstat()
except FileNotFoundError:
return False
return (left_stat.st_dev, left_stat.st_ino) == (right_stat.st_dev, right_stat.st_ino)
def _same_directory_entry(left: Path, right: Path) -> bool:
try:
left_parent = left.parent.resolve(strict=True)
right_parent = right.parent.resolve(strict=True)
left_stat = left.lstat()
except (OSError, RuntimeError):
return False
if left_parent != right_parent:
return False
if left.name == right.name:
return True
same_inode_entries = 0
for entry in left_parent.iterdir():
try:
entry_stat = entry.lstat()
except OSError:
continue
if (entry_stat.st_dev, entry_stat.st_ino) == (left_stat.st_dev, left_stat.st_ino):
same_inode_entries += 1
if same_inode_entries > 1:
return False
return same_inode_entries == 1
def _is_dir_no_follow(path: Path) -> bool:
try:
return stat.S_ISDIR(path.lstat().st_mode)
except FileNotFoundError:
return False
def _entry_contains_no_follow(parent: Path, child: Path) -> bool:
parent_resolved = parent.resolve(strict=True)
child_resolved = child.parent.resolve(strict=True) / child.name
return child_resolved == parent_resolved or parent_resolved in child_resolved.parents
def _rename_no_replace(source: Path, target: Path) -> None:
"""Rename ``source`` -> ``target`` without ever replacing an existing target.
``os.rename()`` REPLACES an existing destination on POSIX, so a separate existence
check before it is a TOCTOU race — a target created in between is silently clobbered.
``os.link()`` is atomic and fails with ``FileExistsError`` if the target exists, so use
link()+unlink() for the common same-directory, regular-file case. Symlinks and
directories cannot be hard-linked; for those use renameat2(RENAME_NOREPLACE) where
available, with a documented platform fallback.
"""
try:
os.link(source, target, follow_symlinks=False)
except FileExistsError as exc:
raise ConflictError("exists", "Destination already exists") from exc
except OSError:
_os_rename_noreplace(source, target)
return
_unlink_source_after_hard_link(source, target)
def _os_rename_noreplace(source: Path, target: Path) -> None:
"""Rename ``source`` to ``target`` without replacing an existing destination."""
try:
_glibc_renameat2_noreplace(source, target)
return
except FileExistsError as exc:
raise ConflictError("exists", "Destination already exists") from exc
except OSError as exc:
if exc.errno == errno.EXDEV:
raise
if exc.errno not in {errno.ENOSYS, errno.EINVAL, errno.ENOTSUP, errno.EOPNOTSUPP}:
raise
except AttributeError:
pass
try:
os.link(source, target, follow_symlinks=False)
except FileExistsError as exc:
raise ConflictError("exists", "Destination already exists") from exc
except OSError as exc:
if exc.errno == errno.EXDEV:
raise
else:
_unlink_source_after_hard_link(source, target)
return
_warn_rename_noreplace_fallback()
if _exists_no_follow(target):
raise ConflictError("exists", "Destination already exists")
# Non-Linux or old libc fallback: POSIX rename can still replace a target
# that appears after this check, notably an empty directory during directory
# rename. Linux deployments should take the atomic renameat2 path above.
source.rename(target)
def _rename_no_replace_into_dir(
source: Path,
target_parent_fd: int | None,
target_parent: Path,
target_name: str,
) -> None:
if target_parent_fd is None:
_rename_no_replace(source, target_parent / target_name)
return
try:
_glibc_renameat2_noreplace_between(
_AT_FDCWD,
os.fsencode(source),
target_parent_fd,
os.fsencode(target_name),
target_name,
)
return
except FileExistsError as exc:
raise ConflictError("exists", "Destination already exists") from exc
except OSError as exc:
if exc.errno == errno.EXDEV:
raise
if exc.errno not in {errno.ENOSYS, errno.EINVAL, errno.ENOTSUP, errno.EOPNOTSUPP}:
raise
except AttributeError:
pass
try:
os.link(source, target_name, dst_dir_fd=target_parent_fd, follow_symlinks=False)
except FileExistsError as exc:
raise ConflictError("exists", "Destination already exists") from exc
except OSError as exc:
if exc.errno == errno.EXDEV:
raise
else:
_unlink_source_after_hard_link_at(source, target_parent_fd, target_name)
return
_warn_rename_noreplace_fallback()
try:
os.stat(target_name, dir_fd=target_parent_fd, follow_symlinks=False)
except FileNotFoundError:
pass
else:
raise ConflictError("exists", "Destination already exists")
os.rename(source, target_name, dst_dir_fd=target_parent_fd)
def _unlink_source_after_hard_link(source: Path, target: Path) -> None:
try:
os.unlink(source)
except OSError:
_remove_created_hard_link(target, source)
raise
def _unlink_source_after_hard_link_at(source: Path, target_parent_fd: int, target_name: str) -> None:
try:
os.unlink(source)
except OSError:
_remove_created_hard_link_at(target_parent_fd, target_name, source)
raise
def _remove_created_hard_link(target: Path, source: Path) -> None:
try:
source_stat = source.lstat()
target_stat = target.lstat()
if (source_stat.st_dev, source_stat.st_ino) == (target_stat.st_dev, target_stat.st_ino):
os.unlink(target)
except OSError:
logger.debug("Failed to remove rollback hard link after no-replace rename failure", exc_info=True)
def _remove_created_hard_link_at(target_parent_fd: int, target_name: str, source: Path) -> None:
try:
source_stat = source.lstat()
target_stat = os.stat(target_name, dir_fd=target_parent_fd, follow_symlinks=False)
if (source_stat.st_dev, source_stat.st_ino) == (target_stat.st_dev, target_stat.st_ino):
os.unlink(target_name, dir_fd=target_parent_fd)
except OSError:
logger.debug("Failed to remove rollback hard link after no-replace rename failure", exc_info=True)
def _glibc_renameat2_noreplace(source: Path, target: Path) -> None:
_glibc_renameat2_noreplace_between(
_AT_FDCWD,
os.fsencode(source),
_AT_FDCWD,
os.fsencode(target),
str(target),
)
def _glibc_renameat2_noreplace_at(dir_fd: int, source_name: str, target_name: str) -> None:
_glibc_renameat2_noreplace_between(
dir_fd,
os.fsencode(source_name),
dir_fd,
os.fsencode(target_name),
target_name,
)
def _glibc_renameat2_noreplace_between(
source_dir_fd: int,
source_name: bytes,
target_dir_fd: int,
target_name: bytes,
target_for_error: str,
) -> None:
if sys.platform != "linux":
raise AttributeError("renameat2 is only available on Linux")
libc = ctypes.CDLL(None, use_errno=True)
renameat2 = libc.renameat2
renameat2.argtypes = [
ctypes.c_int,
ctypes.c_char_p,
ctypes.c_int,
ctypes.c_char_p,
ctypes.c_uint,
]
renameat2.restype = ctypes.c_int
result = renameat2(
source_dir_fd,
source_name,
target_dir_fd,
target_name,
_RENAME_NOREPLACE,
)
if result != 0:
err = ctypes.get_errno()
if err == errno.EEXIST:
raise FileExistsError(err, os.strerror(err), target_for_error)
raise OSError(err, os.strerror(err), target_for_error)
def _warn_rename_noreplace_fallback() -> None:
global _RENAME_NOREPLACE_FALLBACK_WARNED
if _RENAME_NOREPLACE_FALLBACK_WARNED:
return
_RENAME_NOREPLACE_FALLBACK_WARNED = True
logger.warning(
"Atomic no-replace rename is unavailable on this platform; falling back to "
"check-then-rename with a residual empty-directory race."
)
def _stat_existing(path: Path, *, follow_symlinks: bool = True) -> os.stat_result:
try:
return path.stat() if follow_symlinks else path.lstat()
except FileNotFoundError as exc:
raise NotFoundError() from exc
except PermissionError as exc:
raise FileBrowserError("permission_denied", "Permission denied", 403) from exc
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
def _require_stable_resolved_path(path: Path) -> None:
try:
current = path.resolve(strict=True)
except FileNotFoundError as exc:
raise NotFoundError() from exc
except (OSError, RuntimeError, ValueError) as exc:
raise FileBrowserError("invalid_path", str(exc), 400) from exc
if current != path:
raise NotFoundError()
def _require_regular_file(raw: str) -> Path:
path = _resolve_existing_path(raw)
_require_stable_resolved_path(path)
if not path.is_file():
raise FileBrowserError("not_file", "Path is not a regular file", 400)
return path
def _require_directory(raw: str) -> Path:
path = _resolve_existing_path(raw)
if not path.is_dir():
raise FileBrowserError("not_dir", "Path is not a directory", 400)
return path
def _kind_from_mode(mode: int) -> str:
if stat.S_ISLNK(mode):
return "symlink"
if stat.S_ISDIR(mode):
return "dir"
return "file"
def _mtime_seconds(stat_result: os.stat_result) -> float:
return stat_result.st_mtime_ns / 1_000_000_000
_MTIME_CONFLICT_TOLERANCE_SECONDS = 1e-6
_MTIME_TOKEN_STEP_NS = 2_000
_MTIME_TOKEN_COARSE_STEP_NS = 2_000_000_000
def _advance_mtime_token(path: Path, expected_mtime: float) -> None:
stat_result = path.stat()
if abs(_mtime_seconds(stat_result) - float(expected_mtime)) > _MTIME_CONFLICT_TOLERANCE_SECONDS:
return
expected_ns = round(float(expected_mtime) * 1_000_000_000)
baseline_ns = max(stat_result.st_mtime_ns, expected_ns)
for step_ns in (_MTIME_TOKEN_STEP_NS, _MTIME_TOKEN_COARSE_STEP_NS):
os.utime(path, ns=(stat_result.st_atime_ns, baseline_ns + step_ns))
stat_result = path.stat()
if abs(_mtime_seconds(stat_result) - float(expected_mtime)) > _MTIME_CONFLICT_TOLERANCE_SECONDS:
return
raise OSError("filesystem did not preserve an advanced mtime token")
def _extension(path: Path) -> str:
suffix = path.suffix
return suffix[1:].lower() if suffix.startswith(".") else suffix.lower()
def _guess_mime(path: Path) -> str:
return mimetypes.guess_type(str(path))[0] or "application/octet-stream"
def _entry_payload(entry: os.DirEntry[str]) -> dict[str, Any] | None:
try:
stat_result = entry.stat(follow_symlinks=False)
except OSError:
stat_result = None
kind = "file"
size = None
mtime = None
if stat_result is not None:
kind = _kind_from_mode(stat_result.st_mode)
if stat.S_ISREG(stat_result.st_mode):
size = stat_result.st_size
mtime = _mtime_seconds(stat_result)
return {
"name": entry.name,
"kind": kind,
"size": size,
"mtime": mtime,
"ext": _extension(Path(entry.name)) if kind != "dir" else "",
}
def list_directory(raw_path: str, *, show_hidden: bool = False) -> dict[str, Any]:
target = _require_directory(raw_path)
entries: list[dict[str, Any]] = []
scanned_entries = 0
truncated = False
try:
with os.scandir(target) as iterator:
for entry in iterator:
scanned_entries += 1
if not show_hidden and entry.name.startswith("."):
if scanned_entries > MAX_LIST_ENTRIES:
truncated = True
break
continue
payload = _entry_payload(entry)
if payload is not None:
entries.append(payload)
if len(entries) > MAX_LIST_ENTRIES:
entries.pop()
truncated = True
break
if scanned_entries > MAX_LIST_ENTRIES:
truncated = True
break
except PermissionError as exc:
raise FileBrowserError("permission_denied", "Permission denied", 403) from exc
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
entries.sort(key=lambda item: (0 if item["kind"] == "dir" else 1, str(item["name"]).lower(), str(item["name"])))
parent = None if target.parent == target else str(target.parent)
payload = {"ok": True, "path": str(target), "parent": parent, "entries": entries, "truncated": truncated}
if truncated:
payload["limit"] = MAX_LIST_ENTRIES
return payload
def metadata(raw_path: str) -> dict[str, Any]:
path = _resolve_existing_entry_path(raw_path)
stat_result = _stat_existing(path, follow_symlinks=False)
kind = _kind_from_mode(stat_result.st_mode)
size = stat_result.st_size if stat.S_ISREG(stat_result.st_mode) else None
mime = _guess_mime(path) if kind == "file" else None
# Content sniff so the editor can open extensionless / unknown-type text files instead of forcing
# a download. Name/extension alone can't tell a text `LICENSE` from a binary blob.
text = kind == "file" and _looks_like_text(path)
return {
"ok": True,
"name": path.name,
"ext": _extension(path),
"kind": kind,
"size": size,
"mtime": _mtime_seconds(stat_result),
"mime": mime,
"text": text,
}
def file_content(raw_path: str, *, download: bool = False, range_header: str | None = None) -> FileContent:
path = _require_regular_file(raw_path)
stat_result = _stat_existing(path)
if stat_result.st_size > MAX_FILE_BYTES:
raise FileBrowserError("too_large", "File is too large", 413)
mime = _guess_mime(path)
disposition = "attachment" if download or not is_inline_safe_type(mime, INLINE_SAFE_CONTENT_TYPES) else "inline"
try:
flags = os.O_RDONLY
if hasattr(os, "O_NOFOLLOW"):
flags |= os.O_NOFOLLOW
fd = os.open(path, flags)
try:
stat_result = os.fstat(fd)
if not stat.S_ISREG(stat_result.st_mode):
raise FileBrowserError("not_file", "Path is not a regular file", 400)
if stat_result.st_size > MAX_FILE_BYTES:
raise FileBrowserError("too_large", "File is too large", 413)
size = stat_result.st_size
# A media seek reads only the requested span from the already-validated fd.
byte_range = parse_byte_range(range_header, size)
with os.fdopen(fd, "rb", closefd=False) as handle:
if byte_range is None:
data = handle.read(MAX_FILE_BYTES + 1)
else:
handle.seek(byte_range[0])
data = handle.read(byte_range[1] - byte_range[0] + 1)
finally:
os.close(fd)
except FileNotFoundError as exc:
raise NotFoundError() from exc
except PermissionError as exc:
raise FileBrowserError("permission_denied", "Permission denied", 403) from exc
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
if len(data) > MAX_FILE_BYTES:
raise FileBrowserError("too_large", "File is too large", 413)
if byte_range is not None:
# The file may have shrunk after fstat; report the span actually read.
byte_range = (byte_range[0], byte_range[0] + len(data) - 1) if data else None
if byte_range is None:
raise RangeNotSatisfiableError(size)
return FileContent(path=path, mime=mime, disposition=disposition, data=data, size=size, byte_range=byte_range)
def _audit_mutation(op: str, path: Path, **extra: Any) -> None:
if extra:
logger.info("file_browser.%s path=%s extra=%s", op, path, extra)
else:
logger.info("file_browser.%s path=%s", op, path)
def _run_mutation(op: str, path: Path, func, **audit_extra: Any):
_audit_mutation(op, path, **audit_extra)
return func()
def _fsync_dir(path: Path) -> None:
# Persist the directory entry change (e.g. an os.replace rename) so the new
# name survives a crash, not just the file's contents. Best-effort: some
# platforms (Windows) lack O_DIRECTORY or can't fsync a directory.
flags = getattr(os, "O_DIRECTORY", None)
if flags is None:
return
try:
dir_fd = os.open(path, flags)
except OSError:
return
try:
os.fsync(dir_fd)
except OSError:
pass
finally:
os.close(dir_fd)
def _write_lock_for(path: Path) -> threading.Lock:
# Retained for the process lifetime; this keeps compare-and-replace cheap and
# per-path without a cleanup protocol that could race active worker threads.
key = str(path)
with _WRITE_LOCKS_MUTEX:
lock = _WRITE_LOCKS.get(key)
if lock is None:
lock = threading.Lock()
_WRITE_LOCKS[key] = lock
return lock
def write_file(
raw_path: str, content: str, *, expected_mtime: float | None = None, create_only: bool = False
) -> dict[str, Any]:
if not isinstance(content, str):
raise FileBrowserError("invalid_content", "Content must be UTF-8 text", 400)
data = content.encode("utf-8")
if len(data) > MAX_FILE_BYTES:
raise FileBrowserError("too_large", "Content is too large", 413)
# Operate on the entry itself (parent resolved, final component NOT
# symlink-followed) so writing matches the no-follow semantics of
# list/meta/delete and never silently clobbers a symlink's target.
target = _resolve_entry_path(raw_path)
parent = target.parent
if not parent.is_dir():
raise FileBrowserError("not_dir", "Parent is not a directory", 400)
if target.is_symlink():
raise FileBrowserError("is_symlink", "Refusing to write through a symlink", 400)
if target.exists() and not target.is_file():
raise FileBrowserError("not_file", "Path is not a regular file", 400)
if expected_mtime is not None:
try:
current_mtime = _mtime_seconds(target.stat())
except FileNotFoundError as exc:
raise ConflictError("conflict", "File was removed before save") from exc
if abs(current_mtime - float(expected_mtime)) > _MTIME_CONFLICT_TOLERANCE_SECONDS:
raise ConflictError("conflict", "File changed on disk")
def _write() -> dict[str, Any]:
with _write_lock_for(target):
# Re-check at write time to defeat a file→symlink swap between the
# checks above and the replace below.
if target.is_symlink():
raise FileBrowserError("is_symlink", "Refusing to write through a symlink", 400)
if target.exists() and not target.is_file():
raise FileBrowserError("not_file", "Path is not a regular file", 400)
# create_only ("New File"): create the final path atomically with O_EXCL — no temp +
# replace, so it can never overwrite a file another writer/move/external process slipped
# in. O_EXCL fails outright if the path already exists.
if create_only:
try:
excl_fd = os.open(target, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
except FileExistsError as exc:
raise ConflictError("exists", "Path already exists") from exc
except PermissionError as exc:
raise FileBrowserError("permission_denied", "Permission denied", 403) from exc
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
created_ino = os.fstat(excl_fd).st_ino
try:
with os.fdopen(excl_fd, "wb") as handle:
handle.write(data)
handle.flush()
os.fsync(handle.fileno())
except OSError as exc:
# Remove the partial file we created so a retry isn't blocked by a stale
# `exists` — but ONLY if the path still resolves to OUR inode, so we never delete
# a file an external writer slipped in between the failure and here (mirrors the
# hard-link rollback guard).
try:
if os.stat(target).st_ino == created_ino:
os.unlink(target)
except OSError:
pass
raise FileBrowserError("fs_error", str(exc), 400) from exc
_fsync_dir(parent)
return {"ok": True, "mtime": _mtime_seconds(target.stat())}
fd = -1
temp_name = ""
try:
mode = stat.S_IMODE(target.stat().st_mode) if target.exists() else None
fd, temp_name = tempfile.mkstemp(prefix=_WRITE_TEMP_PREFIX, suffix=".tmp", dir=parent)
if mode is not None:
os.fchmod(fd, mode)
with os.fdopen(fd, "wb") as handle:
fd = -1
handle.write(data)
handle.flush()
os.fsync(handle.fileno())
if expected_mtime is not None:
try:
disk_mtime = _mtime_seconds(target.stat())
except FileNotFoundError as exc:
raise ConflictError("conflict", "File was removed before save") from exc
if abs(disk_mtime - float(expected_mtime)) > _MTIME_CONFLICT_TOLERANCE_SECONDS:
raise ConflictError("conflict", "File changed on disk")
_advance_mtime_token(Path(temp_name), expected_mtime)
os.fsync(handle.fileno())
os.replace(temp_name, target)
temp_name = ""
_fsync_dir(parent)
stat_result = target.stat()
return {"ok": True, "mtime": _mtime_seconds(stat_result)}
except PermissionError as exc:
raise FileBrowserError("permission_denied", "Permission denied", 403) from exc
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
finally:
if fd >= 0:
os.close(fd)
if temp_name:
try:
os.unlink(temp_name)
except FileNotFoundError:
pass
return _run_mutation("write", target, _write)
def make_directory(raw_path: str) -> dict[str, Any]:
# Resolve the entry without following a final symlink, so mkdir on a name that
# is a (possibly dangling) symlink reports "exists" instead of creating the
# symlink's target — matching the no-follow semantics of the other mutations.
target = _resolve_entry_path(raw_path)
parent = target.parent
if not parent.is_dir():
raise FileBrowserError("not_dir", "Parent is not a directory", 400)
if _exists_no_follow(target):
raise ConflictError("exists", "Path already exists")
def _mkdir() -> dict[str, Any]:
try:
target.mkdir()
return {"ok": True}
except FileExistsError as exc:
raise ConflictError("exists", "Path already exists") from exc
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
return _run_mutation("mkdir", target, _mkdir)
def _validate_new_name(new_name: str) -> str:
if not isinstance(new_name, str) or not new_name.strip():
raise FileBrowserError("invalid_name", "New name is required", 400)
name = new_name.strip()
if "\x00" in name or name in {".", ".."} or "/" in name or "\\" in name or Path(name).name != name:
raise FileBrowserError("invalid_name", "New name must not contain path separators", 400)
return name
def _resolve_upload_directory(raw_dir: str) -> Path:
# Shares the no-follow directory resolver; only remaps its errors to the upload API's
# historical contract (an unusable destination reads as "not found", not invalid_path).
try:
return resolve_existing_directory(raw_dir)
except NotFoundError as exc:
raise NotFoundError("Destination directory not found") from exc
except FileBrowserError as exc:
if exc.code == "invalid_path":
raise NotFoundError("Destination directory not found") from exc
if exc.code == "not_dir":
raise FileBrowserError("not_dir", "Destination is not a directory", 400) from exc
raise
def _open_stable_upload_directory(directory: Path) -> int | None:
"""Pin the validated destination directory with an fd where the platform can.
The fd keeps the whole streaming window (validate → temp → publish) inside the
directory inode that was validated, so a writable-parent swap cannot redirect the
upload. On platforms that cannot open a directory fd (native Windows), return
``None`` — the upload then operates path-based with no-follow re-checks, the same
stability level as the sibling list/write/rename mutations there.
"""
try:
expected = directory.lstat()
except FileNotFoundError as exc:
raise NotFoundError("Destination directory not found") from exc
except PermissionError as exc:
raise FileBrowserError("permission_denied", "Permission denied", 403) from exc
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
if not stat.S_ISDIR(expected.st_mode):
raise FileBrowserError("not_dir", "Destination is not a directory", 400)
if os.name != "posix":
return None
flags = os.O_RDONLY
if hasattr(os, "O_DIRECTORY"):
flags |= os.O_DIRECTORY
if hasattr(os, "O_NOFOLLOW"):
flags |= os.O_NOFOLLOW
fd = -1
try:
fd = os.open(directory, flags)
current = os.fstat(fd)
if (
not stat.S_ISDIR(current.st_mode)
or (current.st_dev, current.st_ino) != (expected.st_dev, expected.st_ino)
):
raise FileBrowserError("not_dir", "Destination is not a directory", 400)
return fd
except PermissionError as exc:
raise FileBrowserError("permission_denied", "Permission denied", 403) from exc
except OSError as exc:
if exc.errno in {errno.ELOOP, errno.ENOTDIR}:
raise FileBrowserError("not_dir", "Destination is not a directory", 400) from exc
raise FileBrowserError("fs_error", str(exc), 400) from exc
except Exception:
if fd >= 0:
os.close(fd)
raise
# Errnos meaning "this filesystem cannot hard-link" (FAT/exFAT, SMB/CIFS, some NFS):
# fall back to the guarded non-atomic publish below. EPERM is included because CIFS
# reports link refusal as EPERM; a genuine permission problem then surfaces from the
# fallback's replace with the right error anyway.
_LINK_UNSUPPORTED_ERRNOS = {errno.ENOSYS, errno.EINVAL, errno.ENOTSUP, errno.EOPNOTSUPP, errno.EPERM}
def _upload_entry_ref(dir_fd: int | None, directory: Path, name: str) -> str:
"""Name to pass to os.* alongside ``dir_fd``: relative when pinned, absolute when not."""
return name if dir_fd is not None else str(directory / name)
def _validate_upload_target_at(dir_fd: int | None, directory: Path, target_name: str, *, overwrite: bool) -> int | None:
try:
stat_result = os.stat(_upload_entry_ref(dir_fd, directory, target_name), dir_fd=dir_fd, follow_symlinks=False)
except FileNotFoundError:
return None
except PermissionError as exc:
raise FileBrowserError("permission_denied", "Permission denied", 403) from exc
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
if not overwrite or not stat.S_ISREG(stat_result.st_mode):
raise ConflictError("exists", "Destination already exists")
return stat.S_IMODE(stat_result.st_mode)
def _create_upload_temp_at(dir_fd: int | None, directory: Path) -> tuple[int, str]:
flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY
if hasattr(os, "O_NOFOLLOW"):
flags |= os.O_NOFOLLOW
for _ in range(100):
temp_name = f"{_WRITE_TEMP_PREFIX}{uuid.uuid4().hex}.tmp"
try:
return os.open(_upload_entry_ref(dir_fd, directory, temp_name), flags, 0o666, dir_fd=dir_fd), temp_name
except FileExistsError:
continue
except PermissionError as exc:
raise FileBrowserError("permission_denied", "Permission denied", 403) from exc
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
raise FileBrowserError("fs_error", "Could not reserve upload temp file", 400)
def _publish_upload_temp_at(
dir_fd: int | None, directory: Path, temp_name: str, target_name: str, *, overwrite: bool
) -> None:
temp_ref = _upload_entry_ref(dir_fd, directory, temp_name)
target_ref = _upload_entry_ref(dir_fd, directory, target_name)
if overwrite:
os.replace(temp_ref, target_ref, src_dir_fd=dir_fd, dst_dir_fd=dir_fd)
return
# Create-only publish ladder, mirroring _os_rename_noreplace's policy: hard link is
# the atomic no-replace primitive where the filesystem has one; where it doesn't
# (FAT/exFAT/SMB), degrade to a guarded check+replace with the same warning the
# rename fallback emits. renameat2(RENAME_NOREPLACE) is not a useful middle rung
# here: filesystems that refuse link() refuse its flags too.
try:
os.link(temp_ref, target_ref, src_dir_fd=dir_fd, dst_dir_fd=dir_fd, follow_symlinks=False)
except FileExistsError as exc:
raise ConflictError("exists", "Destination already exists") from exc
except OSError as exc:
if exc.errno not in _LINK_UNSUPPORTED_ERRNOS:
raise
_warn_rename_noreplace_fallback()
try:
os.stat(target_ref, dir_fd=dir_fd, follow_symlinks=False)
except FileNotFoundError:
pass
else:
raise ConflictError("exists", "Destination already exists") from exc
os.replace(temp_ref, target_ref, src_dir_fd=dir_fd, dst_dir_fd=dir_fd)
return
_unlink_upload_temp_after_link(dir_fd, directory, temp_name, target_name)
def _unlink_upload_temp_after_link(dir_fd: int | None, directory: Path, temp_name: str, target_name: str) -> None:
try:
os.unlink(_upload_entry_ref(dir_fd, directory, temp_name), dir_fd=dir_fd)
except OSError:
_remove_created_upload_link_at(dir_fd, directory, temp_name, target_name)
raise
def _remove_created_upload_link_at(dir_fd: int | None, directory: Path, temp_name: str, target_name: str) -> None:
try:
temp_stat = os.stat(_upload_entry_ref(dir_fd, directory, temp_name), dir_fd=dir_fd, follow_symlinks=False)
target_stat = os.stat(_upload_entry_ref(dir_fd, directory, target_name), dir_fd=dir_fd, follow_symlinks=False)
if (temp_stat.st_dev, temp_stat.st_ino) == (target_stat.st_dev, target_stat.st_ino):
os.unlink(_upload_entry_ref(dir_fd, directory, target_name), dir_fd=dir_fd)
except OSError:
logger.debug("Failed to remove rollback upload hard link after temp unlink failure", exc_info=True)
def upload_file(
raw_dir: str,
source: BinaryIO,
*,
filename: str | None = None,
name: str | None = None,
overwrite: bool = False,
) -> dict[str, Any]:
directory = _resolve_upload_directory(raw_dir)
target_name = _validate_new_name(name if name is not None and name.strip() else (filename or ""))
target = directory / target_name
dir_fd = _open_stable_upload_directory(directory)
try:
_validate_upload_target_at(dir_fd, directory, target_name, overwrite=overwrite)
def _upload() -> dict[str, Any]:
with _write_lock_for(target):
current_mode = _validate_upload_target_at(dir_fd, directory, target_name, overwrite=overwrite)
fd = -1
temp_name = ""
size = 0
try:
fd, temp_name = _create_upload_temp_at(dir_fd, directory)
if current_mode is not None and hasattr(os, "fchmod"):
os.fchmod(fd, current_mode)
with os.fdopen(fd, "wb") as handle:
fd = -1
while True:
chunk = source.read(_UPLOAD_CHUNK_BYTES)
if not chunk:
break
if not isinstance(chunk, bytes):
chunk = bytes(chunk)
if size + len(chunk) > MAX_FILE_BYTES:
raise FileBrowserError("too_large", "File is too large", 413)
handle.write(chunk)
size += len(chunk)
handle.flush()
os.fsync(handle.fileno())
_publish_upload_temp_at(dir_fd, directory, temp_name, target_name, overwrite=overwrite)
temp_name = ""
if dir_fd is not None:
try:
os.fsync(dir_fd)
except OSError:
pass
else:
_fsync_dir(directory)
stat_result = os.stat(
_upload_entry_ref(dir_fd, directory, target_name), dir_fd=dir_fd, follow_symlinks=False
)
return {
"name": target.name,
"path": str(target),
"size": stat_result.st_size,
"mtime": _mtime_seconds(stat_result),
}
except FileExistsError as exc:
raise ConflictError("exists", "Destination already exists") from exc
except PermissionError as exc:
raise FileBrowserError("permission_denied", "Permission denied", 403) from exc
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
finally:
if fd >= 0:
os.close(fd)
if temp_name:
try:
os.unlink(_upload_entry_ref(dir_fd, directory, temp_name), dir_fd=dir_fd)
except FileNotFoundError:
pass
except OSError:
logger.debug("Failed to clean up upload temp file", exc_info=True)
return _run_mutation("upload", target, _upload, overwrite=overwrite)
finally:
if dir_fd is not None:
os.close(dir_fd)
def rename_path(raw_path: str, new_name: str) -> dict[str, Any]:
source = _resolve_existing_entry_path(raw_path)
name = _validate_new_name(new_name)
target = source.with_name(name)
same_entry = _same_entry_no_follow(source, target)
same_directory_entry = same_entry and _same_directory_entry(source, target)
if same_directory_entry and name == source.name:
return {"ok": True, "path": str(source)}
if _exists_no_follow(target) and not same_directory_entry:
raise ConflictError("exists", "Destination already exists")
def _rename() -> dict[str, Any]:
try:
if same_directory_entry:
source.rename(target)
return {"ok": True, "path": str(target)}
# Atomic no-replace rename: never clobber a destination that appears between the
# precheck above and the rename itself.
_rename_no_replace(source, target)
return {"ok": True, "path": str(target)}
except FileExistsError as exc:
raise ConflictError("exists", "Destination already exists") from exc
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
return _run_mutation("rename", source, _rename)
def move_path(raw_src: str, raw_dst: str, *, overwrite: bool = False) -> dict[str, Any]:
source = _resolve_existing_entry_path(raw_src)
target = _resolve_entry_path(raw_dst)
if source == target:
# Moving onto itself is a no-op; never unlink-then-move (it would delete it). Kept
# before the subtree guard below so an exact self-move stays idempotent rather than
# erroring as "into itself" — the guard is only meant to reject moves into a descendant.
return {"ok": True}
if _is_dir_no_follow(source) and _entry_contains_no_follow(source, target):
raise FileBrowserError("invalid_path", "Cannot move a folder into itself", 400)
if source.is_symlink():
try:
same_target = source.resolve() == target.resolve()
except (OSError, RuntimeError):
same_target = False
if same_target:
raise ConflictError("invalid_move", "Cannot move a symlink onto the file it points to")
parent = target.parent
if not parent.is_dir():
raise FileBrowserError("not_dir", "Destination parent is not a directory", 400)
if _exists_no_follow(target) and not overwrite:
raise ConflictError("exists", "Destination already exists")
if _is_dir_no_follow(target) and not _is_dir_no_follow(source):
# No-follow: only a real directory may overwrite a directory. is_file() follows
# symlinks and is False for a symlink/broken link, which would let a symlink replace
# (and thus erase) a directory under overwrite=True.
raise ConflictError("exists", "Cannot overwrite a directory with a non-directory")
def _move() -> dict[str, Any]:
backup: Path | None = None
source_was_dir = _is_dir_no_follow(source)
target_was_placed = False
def mark_target_placed() -> None:
nonlocal target_was_placed
target_was_placed = True
try:
if not overwrite:
_move_to_absent_target(source, target)
return {"ok": True}
# Re-check at move time for the overwrite path so file-vs-directory
# conflicts are caught before the destination is moved aside.
if _exists_no_follow(target):
if _is_dir_no_follow(target) and not _is_dir_no_follow(source):
raise ConflictError("exists", "Cannot overwrite a directory with a non-directory")
backup = _reserve_backup_path(target)
target.rename(backup)
try:
_move_to_absent_target(source, target, on_target_placed=mark_target_placed)
except Exception:
if backup is not None:
_handle_failed_overwrite_move(
target,
backup,
source_was_dir=source_was_dir,
target_was_placed=target_was_placed,
)
raise
if backup is not None:
_remove_backup_path(backup)
return {"ok": True}
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
return _run_mutation("move", source, _move, dst=str(target), overwrite=overwrite)
def copy_path(raw_src: str, raw_dst: str, *, overwrite: bool = False) -> dict[str, Any]:
"""Copy one entry while preserving modes; copied mtimes are not guaranteed.
Sources are measured before staging and copied without following symlinks.
The 2 GB default cap is configurable through
``AVIBE_FILES_COPY_SIZE_CAP_BYTES``. The completed copy is published from a
sibling temporary entry, so the destination never exposes a partial tree.
"""
source = _resolve_existing_entry_path(raw_src)
target = _resolve_entry_path(raw_dst)
_validate_new_name(_raw_final_component(raw_dst))
source_stat = _stat_existing(source, follow_symlinks=False)
source_is_dir = stat.S_ISDIR(source_stat.st_mode)
source_is_file = stat.S_ISREG(source_stat.st_mode)
source_is_symlink = stat.S_ISLNK(source_stat.st_mode)
if not (source_is_dir or source_is_file or source_is_symlink):
raise FileBrowserError("fs_error", "Unsupported source type", 400)
if source_is_dir and _entry_contains_no_follow(source, target):
raise FileBrowserError("invalid_path", "Cannot copy a folder into itself", 400)
if source_is_symlink:
try:
same_target = source.resolve() == target.resolve()
except (OSError, RuntimeError):
same_target = False
if same_target:
raise ConflictError("invalid_copy", "Cannot copy a symlink onto the file it points to")
if not target.parent.is_dir():
raise FileBrowserError("not_dir", "Destination parent is not a directory", 400)
_validate_copy_target(target, source_is_dir=source_is_dir, overwrite=overwrite)
source_fd: int | None = None
source_link: str | None = None
size_cap = _copy_total_size_cap_bytes()
try:
if source_is_dir and os.name == "posix":
source_fd = _open_copy_directory(source, source_stat)
scan_fd = _open_copy_directory(".", source_stat, dir_fd=source_fd)
try:
_measure_copy_directory_fd(scan_fd, size_cap)
finally:
os.close(scan_fd)
elif source_is_dir:
_measure_copy_directory_path(source, source_stat, size_cap)
elif source_is_file:
_add_copy_size(0, source_stat.st_size, size_cap)
source_fd = _open_copy_file(source, source_stat)
else:
source_link = os.readlink(source)
def _copy() -> dict[str, Any]:
with _write_lock_for(target):
_validate_copy_target(target, source_is_dir=source_is_dir, overwrite=overwrite)
stage: Path | None = None
try:
if source_is_dir:
stage = _new_copy_stage_path(target)
budget = [0]
if source_fd is not None:
copy_fd = _open_copy_directory(".", source_stat, dir_fd=source_fd)
try:
_copy_directory_from_fd(copy_fd, stage, budget, size_cap)
finally:
os.close(copy_fd)
else:
_copy_directory_from_path(source, source_stat, stage, budget, size_cap)
elif source_is_file:
stage = _new_copy_stage_path(target)
assert source_fd is not None
os.lseek(source_fd, 0, os.SEEK_SET)
_copy_file_from_fd(source_fd, stage, source_stat, budget=[0], size_cap=size_cap)
else:
assert source_link is not None
stage = _stage_copy_symlink(target, source_link)
_publish_staged_copy(stage, target, source_is_dir=source_is_dir, overwrite=overwrite)
stage = None
_fsync_dir(target.parent)
return {"ok": True, "path": str(target)}
finally:
if stage is not None:
_remove_copy_stage_best_effort(stage)
return _run_mutation("copy", source, _copy, dst=str(target), overwrite=overwrite)
except FileBrowserError:
raise
except PermissionError as exc:
raise FileBrowserError("permission_denied", "Permission denied", 403) from exc
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
finally:
if source_fd is not None:
os.close(source_fd)
def _move_to_absent_target(
source: Path,
target: Path,
*,
on_target_placed: Callable[[], None] | None = None,
) -> None:
try:
_os_rename_noreplace(source, target)
except OSError as exc:
if exc.errno != errno.EXDEV:
raise
_copy_cross_fs_move_to_absent_target(source, target, on_target_placed=on_target_placed)
else:
if on_target_placed is not None:
on_target_placed()
def _copy_cross_fs_move_to_absent_target(
source: Path,
target: Path,
*,
on_target_placed: Callable[[], None] | None = None,
) -> None:
temp_target: Path | None = _reserve_backup_path(target)
try:
if _is_dir_no_follow(source):
shutil.copytree(source, temp_target, symlinks=True)
else:
shutil.copy2(source, temp_target, follow_symlinks=False)
_os_rename_noreplace(temp_target, target)
temp_target = None
created_target_stat = target.lstat()
if on_target_placed is not None:
on_target_placed()
try:
_remove_backup_path(source)
except OSError:
if _can_delete_placed_target_after_source_removal_failure(source):
_remove_created_cross_fs_move_target(target, source, created_target_stat)
raise
except Exception:
if temp_target is not None:
_remove_path_if_exists(temp_target)
raise
def _reserve_backup_path(target: Path) -> Path:
for _ in range(100):
candidate = target.with_name(f".avibe-overwrite-{uuid.uuid4().hex}")
if not _exists_no_follow(candidate):
return candidate
raise FileBrowserError("fs_error", "Could not reserve overwrite backup path", 400)
def _restore_move_backup(backup: Path, target: Path, *, replace_target: bool) -> None:
if not _exists_no_follow(backup):
return
if replace_target and _exists_no_follow(target):
_remove_backup_path(target)
try:
_os_rename_noreplace(backup, target)
except ConflictError:
if not replace_target:
logger.debug("Leaving overwrite backup in place because target is occupied during restore")
return
raise
def _handle_failed_overwrite_move(
target: Path,
backup: Path,
*,
source_was_dir: bool,
target_was_placed: bool,
) -> None:
if source_was_dir and target_was_placed and _exists_no_follow(target):
_remove_path_if_exists_best_effort(backup)
return
_restore_move_backup(backup, target, replace_target=target_was_placed)
def _can_delete_placed_target_after_source_removal_failure(source: Path) -> bool:
# Non-directory source cleanup uses unlink, which is atomic: if it failed and
# the source still exists, the source copy is intact. Directory cleanup uses
# rmtree, which can partially delete children before raising.
return _exists_no_follow(source) and not _is_dir_no_follow(source)
def _remove_created_cross_fs_move_target(target: Path, source: Path, created_target_stat: os.stat_result) -> None:
try:
target_stat = target.lstat()
if (
_exists_no_follow(source)
and (target_stat.st_dev, target_stat.st_ino)
== (created_target_stat.st_dev, created_target_stat.st_ino)
):
_remove_backup_path(target)
except OSError:
logger.debug("Failed to remove rollback target after cross-filesystem move failure", exc_info=True)
def _remove_backup_path(path: Path) -> None:
if _is_dir_no_follow(path):
shutil.rmtree(path)
else:
path.unlink()
def _remove_path_if_exists(path: Path) -> None:
try:
_remove_backup_path(path)
except FileNotFoundError:
pass
def _remove_path_if_exists_best_effort(path: Path) -> None:
try:
_remove_path_if_exists(path)
except OSError:
logger.debug("Failed to remove move backup after preserving placed target", exc_info=True)
def _copy_total_size_cap_bytes() -> int:
return _env_int(_COPY_TOTAL_SIZE_CAP_ENV, COPY_TOTAL_SIZE_CAP_BYTES)
def _validate_copy_target(target: Path, *, source_is_dir: bool, overwrite: bool) -> None:
if not _exists_no_follow(target):
return
if not overwrite:
raise ConflictError("exists", "Destination already exists")
if _is_dir_no_follow(target) and not source_is_dir:
raise ConflictError("exists", "Cannot overwrite a directory with a non-directory")
def _same_copy_entry(expected: os.stat_result, current: os.stat_result) -> bool:
return (expected.st_dev, expected.st_ino, stat.S_IFMT(expected.st_mode)) == (
current.st_dev,
current.st_ino,
stat.S_IFMT(current.st_mode),
)
def _open_copy_directory(path: str | Path, expected: os.stat_result, *, dir_fd: int | None = None) -> int:
flags = os.O_RDONLY
if hasattr(os, "O_DIRECTORY"):
flags |= os.O_DIRECTORY
if hasattr(os, "O_NOFOLLOW"):
flags |= os.O_NOFOLLOW
fd = os.open(path, flags, dir_fd=dir_fd)
current = os.fstat(fd)
if not stat.S_ISDIR(current.st_mode) or not _same_copy_entry(expected, current):
os.close(fd)
raise FileBrowserError("fs_error", "Source changed during copy", 400)
return fd
def _open_copy_file(path: str | Path, expected: os.stat_result, *, dir_fd: int | None = None) -> int:
flags = os.O_RDONLY
if hasattr(os, "O_NOFOLLOW"):
flags |= os.O_NOFOLLOW
fd = os.open(path, flags, dir_fd=dir_fd)
current = os.fstat(fd)
if not stat.S_ISREG(current.st_mode) or not _same_copy_entry(expected, current):
os.close(fd)
raise FileBrowserError("fs_error", "Source changed during copy", 400)
return fd
def _add_copy_size(total: int, size: int, cap: int) -> int:
total += size
if total > cap:
raise FileBrowserError("too_large", "Copy is too large", 413)
return total
def _measure_copy_directory_fd(dir_fd: int, cap: int) -> int:
total = 0
with os.scandir(dir_fd) as entries:
for entry in entries:
entry_stat = entry.stat(follow_symlinks=False)
if stat.S_ISREG(entry_stat.st_mode):
total = _add_copy_size(total, entry_stat.st_size, cap)
elif stat.S_ISDIR(entry_stat.st_mode):
child_fd = _open_copy_directory(entry.name, entry_stat, dir_fd=dir_fd)
try:
total = _add_copy_size(total, _measure_copy_directory_fd(child_fd, cap - total), cap)
finally:
os.close(child_fd)
elif not stat.S_ISLNK(entry_stat.st_mode):
raise FileBrowserError("fs_error", "Unsupported source type", 400)
return total
def _measure_copy_directory_path(source: Path, expected: os.stat_result, cap: int) -> int:
current = source.lstat()
if not stat.S_ISDIR(current.st_mode) or not _same_copy_entry(expected, current):
raise FileBrowserError("fs_error", "Source changed during copy", 400)
total = 0
with os.scandir(source) as entries:
for entry in entries:
entry_stat = entry.stat(follow_symlinks=False)
child = source / entry.name
if stat.S_ISREG(entry_stat.st_mode):
total = _add_copy_size(total, entry_stat.st_size, cap)
elif stat.S_ISDIR(entry_stat.st_mode):
total = _add_copy_size(
total,
_measure_copy_directory_path(child, entry_stat, cap - total),
cap,
)
elif not stat.S_ISLNK(entry_stat.st_mode):
raise FileBrowserError("fs_error", "Unsupported source type", 400)
return total
def _new_copy_stage_path(target: Path) -> Path:
for _ in range(100):
candidate = target.with_name(f"{_COPY_TEMP_PREFIX}{uuid.uuid4().hex}")
if not _exists_no_follow(candidate):
return candidate
raise FileBrowserError("fs_error", "Could not reserve copy temp path", 400)
def _copy_file_from_fd(
source_fd: int,
target: Path,
source_stat: os.stat_result,
*,
budget: list[int] | None = None,
size_cap: int | None = None,
) -> None:
flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY
if hasattr(os, "O_NOFOLLOW"):
flags |= os.O_NOFOLLOW
target_fd = os.open(target, flags, 0o600)
try:
with os.fdopen(target_fd, "wb") as handle:
target_fd = -1
while True:
chunk = os.read(source_fd, _COPY_CHUNK_BYTES)
if not chunk:
break
if budget is not None and size_cap is not None:
budget[0] = _add_copy_size(budget[0], len(chunk), size_cap)
handle.write(chunk)
handle.flush()
os.fsync(handle.fileno())
mode = stat.S_IMODE(source_stat.st_mode)
if hasattr(os, "fchmod"):
os.fchmod(handle.fileno(), mode)
else:
target.chmod(mode)
finally:
if target_fd >= 0:
os.close(target_fd)
def _copy_symlink_from_fd(source_dir_fd: int, name: str, expected: os.stat_result, target: Path) -> None:
link_target = os.readlink(name, dir_fd=source_dir_fd)
current = os.stat(name, dir_fd=source_dir_fd, follow_symlinks=False)
if not stat.S_ISLNK(current.st_mode) or not _same_copy_entry(expected, current):
raise FileBrowserError("fs_error", "Source changed during copy", 400)
os.symlink(link_target, target)
def _copy_directory_from_fd(dir_fd: int, target: Path, budget: list[int], size_cap: int) -> None:
directory_stat = os.fstat(dir_fd)
target.mkdir(mode=0o700)
with os.scandir(dir_fd) as entries:
for entry in entries:
entry_stat = entry.stat(follow_symlinks=False)
child_target = target / entry.name
if stat.S_ISDIR(entry_stat.st_mode):
child_fd = _open_copy_directory(entry.name, entry_stat, dir_fd=dir_fd)
try:
_copy_directory_from_fd(child_fd, child_target, budget, size_cap)
finally:
os.close(child_fd)
elif stat.S_ISREG(entry_stat.st_mode):
child_fd = _open_copy_file(entry.name, entry_stat, dir_fd=dir_fd)
try:
_copy_file_from_fd(child_fd, child_target, entry_stat, budget=budget, size_cap=size_cap)
finally:
os.close(child_fd)
elif stat.S_ISLNK(entry_stat.st_mode):
_copy_symlink_from_fd(dir_fd, entry.name, entry_stat, child_target)
else:
raise FileBrowserError("fs_error", "Unsupported source type", 400)
target.chmod(stat.S_IMODE(directory_stat.st_mode))
def _copy_directory_from_path(
source: Path,
expected: os.stat_result,
target: Path,
budget: list[int],
size_cap: int,
) -> None:
directory_stat = source.lstat()
if not stat.S_ISDIR(directory_stat.st_mode) or not _same_copy_entry(expected, directory_stat):
raise FileBrowserError("fs_error", "Source changed during copy", 400)
target.mkdir(mode=0o700)
with os.scandir(source) as entries:
for entry in entries:
entry_stat = entry.stat(follow_symlinks=False)
child_source = source / entry.name
child_target = target / entry.name
if stat.S_ISDIR(entry_stat.st_mode):
_copy_directory_from_path(child_source, entry_stat, child_target, budget, size_cap)
elif stat.S_ISREG(entry_stat.st_mode):
child_fd = _open_copy_file(child_source, entry_stat)
try:
_copy_file_from_fd(child_fd, child_target, entry_stat, budget=budget, size_cap=size_cap)
finally:
os.close(child_fd)
elif stat.S_ISLNK(entry_stat.st_mode):
link_target = os.readlink(child_source)
current_link = child_source.lstat()
if not stat.S_ISLNK(current_link.st_mode) or not _same_copy_entry(entry_stat, current_link):
raise FileBrowserError("fs_error", "Source changed during copy", 400)
os.symlink(link_target, child_target)
else:
raise FileBrowserError("fs_error", "Unsupported source type", 400)
target.chmod(stat.S_IMODE(directory_stat.st_mode))
def _stage_copy_symlink(target: Path, link_target: str) -> Path:
for _ in range(100):
stage = _new_copy_stage_path(target)
try:
os.symlink(link_target, stage)
return stage
except FileExistsError:
continue
raise FileBrowserError("fs_error", "Could not reserve copy temp path", 400)
def _publish_staged_copy(stage: Path, target: Path, *, source_is_dir: bool, overwrite: bool) -> None:
if not overwrite:
_os_rename_noreplace(stage, target)
return
if not _exists_no_follow(target):
_os_rename_noreplace(stage, target)
return
if not source_is_dir:
if _is_dir_no_follow(target):
raise ConflictError("exists", "Cannot overwrite a directory with a non-directory")
try:
os.replace(stage, target)
except (IsADirectoryError, NotADirectoryError) as exc:
raise ConflictError("exists", "Destination type changed during copy") from exc
return
backup = _reserve_backup_path(target)
_os_rename_noreplace(target, backup)
published = False
try:
_os_rename_noreplace(stage, target)
published = True
except Exception:
if not _exists_no_follow(target):
try:
_os_rename_noreplace(backup, target)
backup = None
except Exception:
logger.exception("Failed to restore copy overwrite backup")
raise
finally:
if published and backup is not None:
_remove_copy_stage_best_effort(backup)
def _remove_copy_stage_best_effort(path: Path) -> None:
try:
if _is_dir_no_follow(path):
_make_copy_tree_removable(path)
shutil.rmtree(path)
else:
path.unlink()
except FileNotFoundError:
pass
except OSError:
logger.debug("Failed to remove copy staging path", exc_info=True)
def _make_copy_tree_removable(root: Path) -> None:
stack = [(root, root.lstat())]
while stack:
directory, expected = stack.pop()
_make_copy_directory_writable(directory, expected)
with os.scandir(directory) as entries:
for entry in entries:
entry_stat = entry.stat(follow_symlinks=False)
if stat.S_ISDIR(entry_stat.st_mode):
stack.append((directory / entry.name, entry_stat))
def _make_copy_directory_writable(path: Path, expected: os.stat_result) -> None:
mode = stat.S_IMODE(expected.st_mode) | stat.S_IRUSR | stat.S_IWUSR | stat.S_IXUSR
if os.name == "posix":
fd = _open_copy_directory(path, expected)
try:
os.fchmod(fd, mode)
finally:
os.close(fd)
return
current = path.lstat()
if not stat.S_ISDIR(current.st_mode) or not _same_copy_entry(expected, current):
raise FileBrowserError("fs_error", "Copy staging tree changed during cleanup", 400)
path.chmod(mode)
def _delete_undo_remove_path(path: Path) -> bool:
try:
_remove_path_if_exists(path)
return True
except OSError:
logger.debug("Failed to remove delete undo staging path", exc_info=True)
return False
def _env_int(name: str, default: int) -> int:
raw = os.environ.get(name)
if raw is None or raw == "":
return default
try:
return max(0, int(raw))
except ValueError:
logger.warning("Ignoring invalid integer value for %s", name)
return default
def _delete_undo_ttl_seconds() -> int:
return _env_int(_DELETE_UNDO_TTL_ENV, DELETE_UNDO_TTL_SECONDS)
def _delete_undo_max_entries() -> int:
return _env_int(_DELETE_UNDO_MAX_ENTRIES_ENV, DELETE_UNDO_MAX_ENTRIES)
def _delete_undo_entry_size_cap_bytes() -> int:
return _env_int(_DELETE_UNDO_ENTRY_SIZE_CAP_ENV, DELETE_UNDO_ENTRY_SIZE_CAP_BYTES)
def _delete_undo_total_size_cap_bytes() -> int:
return _env_int(_DELETE_UNDO_TOTAL_SIZE_CAP_ENV, DELETE_UNDO_TOTAL_SIZE_CAP_BYTES)
def _delete_undo_root() -> Path:
from config import paths
return paths.get_runtime_dir() / _DELETE_UNDO_DIR_NAME
def _ensure_delete_undo_root() -> Path:
root = _delete_undo_root()
root.mkdir(parents=True, exist_ok=True)
stat_result = root.lstat()
if stat.S_ISLNK(stat_result.st_mode) or not stat.S_ISDIR(stat_result.st_mode):
raise OSError(errno.ENOTDIR, "delete undo staging root is not a directory", str(root))
return root
def _entry_size_no_follow(path: Path, *, cap: int) -> int | None:
total = 0
stack = [path]
while stack:
current = stack.pop()
try:
stat_result = current.lstat()
except OSError:
return None
total += max(0, stat_result.st_size)
if total > cap:
return total
if not stat.S_ISDIR(stat_result.st_mode):
continue
try:
with os.scandir(current) as iterator:
stack.extend(Path(entry.path) for entry in iterator)
except OSError:
return None
return total
def _directory_empty_no_follow(path: Path) -> bool | None:
try:
with os.scandir(path) as iterator:
return next(iterator, None) is None
except OSError:
return None
def _same_staged_entry(left: os.stat_result, right: os.stat_result) -> bool:
return (
left.st_dev,
left.st_ino,
left.st_mode,
left.st_size,
) == (
right.st_dev,
right.st_ino,
right.st_mode,
right.st_size,
)
def _delete_staging_type_matches(original: os.stat_result, current: os.stat_result) -> bool:
original_is_dir = stat.S_ISDIR(original.st_mode)
current_is_dir = stat.S_ISDIR(current.st_mode)
if original_is_dir != current_is_dir:
return False
return True
def _write_delete_undo_metadata(path: Path, payload: dict[str, Any]) -> None:
data = json.dumps(payload, sort_keys=True).encode("utf-8")
fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
try:
os.write(fd, data)
os.fsync(fd)
finally:
os.close(fd)
def _replace_delete_undo_metadata(path: Path, payload: dict[str, Any]) -> None:
temp_path = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
try:
_write_delete_undo_metadata(temp_path, payload)
os.replace(temp_path, path)
_fsync_dir(path.parent)
except OSError:
try:
temp_path.unlink()
except FileNotFoundError:
pass
raise
def _delete_undo_entry_from_dir(directory: Path) -> DeleteUndoEntry | None:
if not re.fullmatch(r"[0-9a-f]{32}", directory.name):
return None
if not directory.is_dir() or directory.is_symlink():
return None
metadata_path = directory / _DELETE_UNDO_METADATA_NAME
entry_path = directory / _DELETE_UNDO_ENTRY_NAME
try:
payload = json.loads(metadata_path.read_text(encoding="utf-8"))
original_path = Path(str(payload["original_path"]))
parent_dev = int(payload["parent_dev"])
parent_ino = int(payload["parent_ino"])
deleted_at = float(payload["deleted_at"])
metadata_size = int(payload["size"])
except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError):
return None
if (
not original_path.is_absolute()
or "\x00" in str(original_path)
or deleted_at < 0
or metadata_size < 0
or parent_dev < 0
or parent_ino < 0
):
return None
if not _exists_no_follow(entry_path):
return None
effective_size_cap = min(_delete_undo_entry_size_cap_bytes(), _delete_undo_total_size_cap_bytes())
if effective_size_cap <= 0:
return None
actual_size = _entry_size_no_follow(entry_path, cap=effective_size_cap)
if actual_size is None:
return None
size = max(metadata_size, actual_size)
return DeleteUndoEntry(
token=directory.name,
directory=directory,
entry_path=entry_path,
metadata_path=metadata_path,
original_path=original_path,
parent_dev=parent_dev,
parent_ino=parent_ino,
deleted_at=deleted_at,
size=size,
)
def _cancel_delete_undo_expiry_timer_locked() -> None:
global _DELETE_UNDO_EXPIRY_TIMER
global _DELETE_UNDO_EXPIRY_TIMER_DEADLINE
global _DELETE_UNDO_EXPIRY_TIMER_ROOT
if _DELETE_UNDO_EXPIRY_TIMER is not None:
_DELETE_UNDO_EXPIRY_TIMER.cancel()
_DELETE_UNDO_EXPIRY_TIMER = None
_DELETE_UNDO_EXPIRY_TIMER_DEADLINE = None
_DELETE_UNDO_EXPIRY_TIMER_ROOT = None
def _schedule_delete_undo_expiry_locked(root: Path, entries: list[DeleteUndoEntry], *, now: float) -> None:
global _DELETE_UNDO_EXPIRY_TIMER
global _DELETE_UNDO_EXPIRY_TIMER_DEADLINE
global _DELETE_UNDO_EXPIRY_TIMER_ROOT
ttl = _delete_undo_ttl_seconds()
future_deadlines = [entry.deleted_at + ttl for entry in entries if entry.deleted_at + ttl > now]
if not future_deadlines:
_cancel_delete_undo_expiry_timer_locked()
return
deadline = min(future_deadlines)
if (
_DELETE_UNDO_EXPIRY_TIMER is not None
and _DELETE_UNDO_EXPIRY_TIMER.is_alive()
and _DELETE_UNDO_EXPIRY_TIMER_DEADLINE == deadline
and _DELETE_UNDO_EXPIRY_TIMER_ROOT == root
):
return
_cancel_delete_undo_expiry_timer_locked()
timer = threading.Timer(max(0.0, deadline - now), _run_delete_undo_expiry_timer, args=(root,))
timer.daemon = True
_DELETE_UNDO_EXPIRY_TIMER = timer
_DELETE_UNDO_EXPIRY_TIMER_DEADLINE = deadline
_DELETE_UNDO_EXPIRY_TIMER_ROOT = root
timer.start()
def _run_delete_undo_expiry_timer(root: Path) -> None:
with _DELETE_UNDO_LOCK:
try:
root_stat = root.lstat()
if stat.S_ISLNK(root_stat.st_mode) or not stat.S_ISDIR(root_stat.st_mode):
_cancel_delete_undo_expiry_timer_locked()
return
_purge_delete_undo_store_locked(root)
except OSError:
_cancel_delete_undo_expiry_timer_locked()
logger.debug("Delete undo expiry purge failed", exc_info=True)
def _purge_delete_undo_store_locked(
root: Path, *, now: float | None = None, schedule_expiry: bool = True
) -> list[DeleteUndoEntry]:
current_time = time.time() if now is None else now
ttl = _delete_undo_ttl_seconds()
entries: list[DeleteUndoEntry] = []
try:
children = list(root.iterdir())
except FileNotFoundError:
if schedule_expiry:
_cancel_delete_undo_expiry_timer_locked()
return []
for child in children:
entry = _delete_undo_entry_from_dir(child)
if entry is None or current_time - entry.deleted_at > ttl:
if _delete_undo_remove_path(child):
_fsync_dir(root)
continue
if entry is None:
continue
elif entry.size > min(_delete_undo_entry_size_cap_bytes(), _delete_undo_total_size_cap_bytes()):
if _delete_undo_remove_path(child):
_fsync_dir(root)
continue
entries.append(entry)
entries.sort(key=lambda item: (item.deleted_at, item.token))
max_entries = _delete_undo_max_entries()
while len(entries) > max_entries:
if not _evict_one_delete_undo_entry(root, entries):
break
total_cap = _delete_undo_total_size_cap_bytes()
total_size = sum(entry.size for entry in entries)
while entries and total_size > total_cap:
if not _evict_one_delete_undo_entry(root, entries):
break
total_size = sum(entry.size for entry in entries)
if schedule_expiry:
_schedule_delete_undo_expiry_locked(root, entries, now=current_time)
return entries
def _evict_one_delete_undo_entry(root: Path, entries: list[DeleteUndoEntry]) -> bool:
for index, victim in enumerate(entries):
if _delete_undo_remove_path(victim.directory):
entries.pop(index)
_fsync_dir(root)
return True
return False
def _delete_undo_store_within_caps(entries: list[DeleteUndoEntry]) -> bool:
return (
len(entries) <= _delete_undo_max_entries()
and sum(entry.size for entry in entries) <= _delete_undo_total_size_cap_bytes()
)
def _discard_delete_undo_stage_or_raise(stage_dir: Path, root: Path, *, target_parent: Path | None = None) -> None:
if not _delete_undo_remove_path(stage_dir):
raise FileBrowserError("fs_error", "Failed to remove delete undo staging entry", 400)
if target_parent is not None:
_fsync_dir(target_parent)
_fsync_dir(root)
def _restore_staged_directory_after_not_empty(staged_entry: Path, target: Path, stage_dir: Path, root: Path) -> None:
try:
_rename_no_replace(staged_entry, target)
except ConflictError as exc:
raise FileBrowserError("fs_error", "Failed to restore non-empty directory after staging", 400) from exc
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
_discard_delete_undo_stage_or_raise(stage_dir, root, target_parent=target.parent)
def _delete_undo_parent_matches(entry: DeleteUndoEntry) -> bool:
try:
parent_stat = entry.original_path.parent.lstat()
except OSError:
return False
return (
stat.S_ISDIR(parent_stat.st_mode)
and not stat.S_ISLNK(parent_stat.st_mode)
and (parent_stat.st_dev, parent_stat.st_ino) == (entry.parent_dev, entry.parent_ino)
)
def _open_verified_delete_undo_parent(entry: DeleteUndoEntry) -> int | None:
if os.name != "posix":
if _delete_undo_parent_matches(entry):
return None
raise FileBrowserError("expired", "Undo token expired or unavailable", 410)
flags = os.O_RDONLY
if hasattr(os, "O_DIRECTORY"):
flags |= os.O_DIRECTORY
if hasattr(os, "O_NOFOLLOW"):
flags |= os.O_NOFOLLOW
fd = -1
try:
fd = os.open(entry.original_path.parent, flags)
parent_stat = os.fstat(fd)
if (
not stat.S_ISDIR(parent_stat.st_mode)
or stat.S_ISLNK(parent_stat.st_mode)
or (parent_stat.st_dev, parent_stat.st_ino) != (entry.parent_dev, entry.parent_ino)
):
raise FileBrowserError("expired", "Undo token expired or unavailable", 410)
return fd
except FileBrowserError:
if fd >= 0:
os.close(fd)
raise
except OSError as exc:
if fd >= 0:
os.close(fd)
if exc.errno in {errno.ENOENT, errno.ENOTDIR, errno.ELOOP}:
raise FileBrowserError("expired", "Undo token expired or unavailable", 410) from exc
if exc.errno in {errno.EACCES, errno.EPERM} or isinstance(exc, PermissionError):
raise FileBrowserError("permission_denied", "Permission denied", 403) from exc
raise FileBrowserError("fs_error", str(exc), 400) from exc
def _delete_undo_target_exists(parent_fd: int | None, target: Path) -> bool:
if parent_fd is None:
return _exists_no_follow(target)
try:
os.stat(target.name, dir_fd=parent_fd, follow_symlinks=False)
return True
except FileNotFoundError:
return False
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
def _fsync_delete_undo_parent(parent_fd: int | None, parent: Path) -> None:
if parent_fd is None:
_fsync_dir(parent)
return
try:
os.fsync(parent_fd)
except OSError:
pass
def _ensure_delete_undo_initialized() -> None:
global _DELETE_UNDO_INITIALIZED
if _DELETE_UNDO_INITIALIZED:
return
with _DELETE_UNDO_LOCK:
if _DELETE_UNDO_INITIALIZED:
return
try:
root = _ensure_delete_undo_root()
_purge_delete_undo_store_locked(root)
except OSError:
logger.debug("Delete undo staging initialization failed", exc_info=True)
return
_DELETE_UNDO_INITIALIZED = True
def _purge_delete_undo_store_best_effort() -> None:
_ensure_delete_undo_initialized()
with _DELETE_UNDO_LOCK:
try:
root = _ensure_delete_undo_root()
_purge_delete_undo_store_locked(root)
except OSError:
logger.debug("Delete undo staging purge failed", exc_info=True)
def _delete_permanently(target: Path, target_stat: os.stat_result, *, recursive: bool) -> dict[str, Any]:
try:
if stat.S_ISDIR(target_stat.st_mode):
if recursive:
shutil.rmtree(target)
else:
target.rmdir()
else:
target.unlink()
return {"ok": True, "undo_token": None, "undo_expires_seconds": None}
except OSError as exc:
if stat.S_ISDIR(target_stat.st_mode) and not recursive and exc.errno in {errno.ENOTEMPTY, errno.EEXIST}:
raise ConflictError("not_empty", "Directory is not empty") from exc
if isinstance(exc, FileNotFoundError):
raise NotFoundError() from exc
if isinstance(exc, PermissionError):
raise FileBrowserError("permission_denied", "Permission denied", 403) from exc
raise FileBrowserError("fs_error", str(exc), 400) from exc
def _stage_delete_for_undo(target: Path, target_stat: os.stat_result, *, recursive: bool) -> dict[str, Any] | None:
entry_size_cap = _delete_undo_entry_size_cap_bytes()
total_size_cap = _delete_undo_total_size_cap_bytes()
effective_size_cap = min(entry_size_cap, total_size_cap)
if effective_size_cap <= 0:
return None
_ensure_delete_undo_initialized()
ttl = _delete_undo_ttl_seconds()
now = time.time()
token = uuid.uuid4().hex
with _DELETE_UNDO_LOCK:
stage_dir: Path | None = None
renamed_to_stage = False
try:
root = _ensure_delete_undo_root()
existing_entries = _purge_delete_undo_store_locked(root, now=now)
if not _delete_undo_store_within_caps(existing_entries):
return None
current_stat = target.lstat()
if not _delete_staging_type_matches(target_stat, current_stat):
return None
current_is_dir = stat.S_ISDIR(current_stat.st_mode)
if current_is_dir and not recursive and _directory_empty_no_follow(target) is not True:
return None
parent_stat = target.parent.lstat()
if not stat.S_ISDIR(parent_stat.st_mode) or stat.S_ISLNK(parent_stat.st_mode):
return None
size = _entry_size_no_follow(target, cap=effective_size_cap)
if size is None or size > effective_size_cap:
return None
post_size_stat = target.lstat()
if not _same_staged_entry(current_stat, post_size_stat):
return None
stage_dir = root / token
stage_dir.mkdir(mode=0o700)
_fsync_dir(root)
metadata_path = stage_dir / _DELETE_UNDO_METADATA_NAME
staged_entry = stage_dir / _DELETE_UNDO_ENTRY_NAME
metadata_payload = {
"original_path": str(target),
"parent_dev": parent_stat.st_dev,
"parent_ino": parent_stat.st_ino,
"deleted_at": now,
"size": size,
}
_write_delete_undo_metadata(metadata_path, metadata_payload)
_fsync_dir(stage_dir)
pre_rename_stat = target.lstat()
if not _same_staged_entry(post_size_stat, pre_rename_stat):
_delete_undo_remove_path(stage_dir)
_fsync_dir(root)
return None
if stat.S_ISDIR(pre_rename_stat.st_mode) and not recursive and _directory_empty_no_follow(target) is not True:
_delete_undo_remove_path(stage_dir)
_fsync_dir(root)
return None
_os_rename_noreplace(target, staged_entry)
renamed_to_stage = True
if current_is_dir and not recursive and _directory_empty_no_follow(staged_entry) is not True:
_restore_staged_directory_after_not_empty(staged_entry, target, stage_dir, root)
raise ConflictError("not_empty", "Directory is not empty")
staged_size = _entry_size_no_follow(staged_entry, cap=effective_size_cap)
if staged_size is None or staged_size > effective_size_cap:
_discard_delete_undo_stage_or_raise(stage_dir, root, target_parent=target.parent)
return {"ok": True, "undo_token": None, "undo_expires_seconds": None}
if staged_size != size:
metadata_payload["size"] = staged_size
_replace_delete_undo_metadata(metadata_path, metadata_payload)
except OSError as exc:
if stage_dir is not None:
_discard_delete_undo_stage_or_raise(
stage_dir,
root,
target_parent=target.parent if renamed_to_stage else None,
)
if renamed_to_stage:
logger.debug("Delete undo staging failed after rename; treating delete as permanent: %s", exc)
return {"ok": True, "undo_token": None, "undo_expires_seconds": None}
logger.debug("Delete undo staging failed; falling back to permanent delete: %s", exc)
return None
_fsync_dir(stage_dir)
_fsync_dir(target.parent)
try:
entries = _purge_delete_undo_store_locked(root, now=now)
staged_retained = any(entry.token == token for entry in entries) and _delete_undo_store_within_caps(entries)
except OSError:
logger.debug("Delete undo staging cap purge failed after staging", exc_info=True)
staged_retained = True
if not staged_retained:
_discard_delete_undo_stage_or_raise(stage_dir, root, target_parent=target.parent)
return {"ok": True, "undo_token": None, "undo_expires_seconds": None}
return {"ok": True, "undo_token": token, "undo_expires_seconds": ttl}
def _validate_delete_undo_token(token: str) -> str:
if not isinstance(token, str) or not re.fullmatch(r"[0-9a-f]{32}", token):
raise FileBrowserError("expired", "Undo token expired or unavailable", 410)
return token
def delete_path(raw_path: str, *, recursive: bool = False) -> dict[str, Any]:
target = _resolve_existing_entry_path(raw_path)
if target == target.parent:
# A filesystem root (/, or a drive root on Windows). Never deletable — a recursive
# delete here would try to wipe everything the process can reach.
raise FileBrowserError("invalid_path", "Refusing to delete a filesystem root", 400)
target_stat = _stat_existing(target, follow_symlinks=False)
def _delete() -> dict[str, Any]:
_purge_delete_undo_store_best_effort()
staged = _stage_delete_for_undo(target, target_stat, recursive=recursive)
if staged is not None:
return staged
return _delete_permanently(target, target_stat, recursive=recursive)
return _run_mutation("delete", target, _delete, recursive=recursive)
def undo_delete_path(token: str) -> dict[str, Any]:
token = _validate_delete_undo_token(token)
_ensure_delete_undo_initialized()
with _DELETE_UNDO_LOCK:
now = time.time()
try:
root = _ensure_delete_undo_root()
_purge_delete_undo_store_locked(root, now=now)
except OSError as exc:
raise FileBrowserError("expired", "Undo token expired or unavailable", 410) from exc
stage_dir = root / token
entry = _delete_undo_entry_from_dir(stage_dir)
if entry is None or now - entry.deleted_at > _delete_undo_ttl_seconds():
_delete_undo_remove_path(stage_dir)
raise FileBrowserError("expired", "Undo token expired or unavailable", 410)
try:
parent_fd = _open_verified_delete_undo_parent(entry)
except FileBrowserError as exc:
if exc.code == "expired":
_delete_undo_remove_path(stage_dir)
_fsync_dir(root)
raise
try:
if _delete_undo_target_exists(parent_fd, entry.original_path):
raise ConflictError("exists", "Original path already exists")
def _restore() -> dict[str, Any]:
try:
_rename_no_replace_into_dir(
entry.entry_path,
parent_fd,
entry.original_path.parent,
entry.original_path.name,
)
except ConflictError:
raise
except OSError as exc:
raise FileBrowserError("fs_error", str(exc), 400) from exc
_fsync_delete_undo_parent(parent_fd, entry.original_path.parent)
_fsync_dir(entry.directory)
try:
entry.metadata_path.unlink()
entry.directory.rmdir()
_fsync_dir(root)
except OSError:
logger.debug("Failed to clean up delete undo staging directory after restore", exc_info=True)
return {"restored_path": str(entry.original_path)}
return _run_mutation("delete_undo", entry.original_path, _restore)
finally:
if parent_fd is not None:
os.close(parent_fd)
# ---------------------------------------------------------------------------
# Cross-file search + replace
#
# Search walks an absolute root directory (the folder open in the editor) and
# scans text files line-by-line. Matching is unified through a single compiled
# regex so search, replace, and the UI preview all agree on what a "match" is.
# Replace is per-line (same semantics as search/preview) and snapshots the
# original text so the whole batch can be undone with one click.
# ---------------------------------------------------------------------------
SEARCH_MAX_FILE_BYTES = 2 * 1024 * 1024
SEARCH_MAX_MATCHES = 1000
SEARCH_MAX_FILES = 200
SEARCH_LINE_PREVIEW_CHARS = 400
SEARCH_PREVIEW_CONTEXT = 60
SEARCH_NAME_MAX_RESULTS = 500
_BINARY_SNIFF_BYTES = 8192
# Directories never worth searching — VCS metadata, dependency/build output,
# caches. Pruned during the walk so we never descend into huge noise trees.
SEARCH_SKIP_DIRS = frozenset(
{
".git", ".hg", ".svn", "node_modules", ".venv", "venv", "__pycache__",
".mypy_cache", ".pytest_cache", ".ruff_cache", ".cache", "dist", "build",
".next", ".turbo", ".parcel-cache", ".gradle", "target", ".idea", ".tox",
}
)
_UNDO_TTL_SECONDS = 600.0
_UNDO_MAX_TOKENS = 32
_UNDO_MAX_BYTES = 64 * 1024 * 1024
_UNDO_STORE: dict[str, dict[str, Any]] = {}
_UNDO_LOCK = threading.Lock()
def _is_word_char(ch: str) -> bool:
return re.match(r"\w", ch) is not None
def _compile_search_matcher(query: str, *, regex: bool, case_sensitive: bool, whole_word: bool) -> "re.Pattern[str]":
if not isinstance(query, str) or query == "":
raise FileBrowserError("invalid_query", "Search query is required", 400)
pattern = query if regex else re.escape(query)
if whole_word:
# Guard an edge with \b only when the query's edge char is itself a word char. A symbol query
# like "C++" or "foo()" ends in a non-word char, and \b needs a word/non-word transition, so
# a both-sides \b would make it never match. (For regex queries the edge is taken from the raw
# query text — a heuristic, but it fixes the common literal symbol case.)
prefix = r"\b" if _is_word_char(query[0]) else ""
suffix = r"\b" if _is_word_char(query[-1]) else ""
pattern = f"{prefix}(?:{pattern}){suffix}"
flags = 0 if case_sensitive else re.IGNORECASE
try:
return re.compile(pattern, flags)
except re.error as exc:
raise FileBrowserError("invalid_regex", f"Invalid regular expression: {exc}", 400) from exc
def _split_globs(raw: str | None) -> list[str]:
if not raw:
return []
return [piece.strip() for piece in str(raw).replace("\n", ",").split(",") if piece.strip()]
def _match_globs(rel_posix: str, patterns: list[str]) -> bool:
name = rel_posix.rsplit("/", 1)[-1]
for pat in patterns:
# A leading `**/` should also match at the root: fnmatch's `**/` needs a real slash, so
# `**/*.py` would miss root `foo.py` and `**/dist/**` would miss root `dist/a.ts`. Also try
# the pattern with the `**/` prefix stripped.
forms = [pat, pat[3:]] if pat.startswith("**/") else [pat]
if any(fnmatch.fnmatch(rel_posix, form) for form in forms) or fnmatch.fnmatch(name, pat):
return True
return False
def _looks_like_text(path: Path) -> bool:
"""Sniff whether a regular file is text (editable) by CONTENT, independent of name/extension.
Mirrors the search reader's binary check: a NUL byte in the first chunk, or a head that decodes
to mostly replacement characters, marks it binary. This lets extensionless text files (LICENSE,
README, notes, config) open in the editor while true binaries (images, executables, archives)
stay on the download path. Reads at most the sniff window, so it's cheap even for huge files.
"""
try:
if path.is_symlink() or not path.is_file():
return False
with open(path, "rb") as handle:
head = handle.read(_BINARY_SNIFF_BYTES)
except OSError:
return False
if not head:
return True # an empty file is editable
if b"\x00" in head:
return False
# Decode leniently and require almost no replacement characters: real text has none (or a single
# multibyte char split at the sniff boundary), while binary content produces many.
decoded = head.decode("utf-8", errors="replace")
return decoded.count("�") <= max(1, len(decoded) // 100)
def _read_file_text(path: Path, *, lossy: bool) -> tuple[str | None, float | None]:
"""Read a regular text file for search/replace; returns (text, mtime) or (None, None) to skip.
Skips directories, oversized files, and binaries (NUL in the first chunk). ``lossy`` controls
undecodable bytes: search previews tolerate replacement characters; replace must not, so it
returns None and leaves the file alone. The mtime is captured from the stat taken BEFORE the
read, so it corresponds to (at most) the content returned — search hands that mtime back as the
replace baseline, and a change during the read window then fails the later mtime check.
"""
# The rest of the file browser treats symlinks as no-follow / non-editable; mirror that here so
# search/replace can't follow a link out of the opened root (e.g. a planted
# ``secret -> ~/.ssh/id_rsa``) and surface or rewrite content outside the tree.
if path.is_symlink():
return None, None
try:
st = path.stat()
except OSError:
return None, None
if not stat.S_ISREG(st.st_mode) or st.st_size > SEARCH_MAX_FILE_BYTES:
return None, None
mtime = _mtime_seconds(st)
try:
with open(path, "rb") as handle:
head = handle.read(_BINARY_SNIFF_BYTES)
if b"\x00" in head:
return None, None
# Bound the read to the size limit even if the file grew since the stat above (TOCTOU, or
# a growing special file), so one read can't pull unbounded bytes into memory. For
# replace, a file that grew also fails the later mtime check, so no truncated write lands.
data = head + handle.read(max(0, SEARCH_MAX_FILE_BYTES - len(head)))
except OSError:
return None, None
try:
return data.decode("utf-8"), mtime
except UnicodeDecodeError:
if not lossy:
return None, None
return data.decode("utf-8", errors="replace"), mtime
def _iter_search_files(root: Path, include: list[str], exclude: list[str]):
"""Yield (path, rel_posix) for every candidate file under ``root``."""
exclude_names = [pat for pat in exclude if "/" not in pat]
for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
dirnames[:] = sorted(
d for d in dirnames if d not in SEARCH_SKIP_DIRS and not _match_globs(d, exclude_names)
)
base = Path(dirpath)
for name in sorted(filenames):
fpath = base / name
rel = fpath.relative_to(root).as_posix()
if include and not _match_globs(rel, include):
continue
if exclude and _match_globs(rel, exclude):
continue
yield fpath, rel
def _utf16_len(s: str) -> int:
# Python indexes strings by code point; the React preview (String.slice) and Monaco columns
# count UTF-16 code units. Convert so a non-BMP char (emoji, etc.) before a match doesn't shift
# the highlight / jump selection.
return len(s.encode("utf-16-le")) // 2
def _preview_for_match(line: str, start: int, end: int) -> tuple[str, int, int]:
"""Build a preview snippet that always contains the match, with UTF-16 col/end into it.
Short lines are returned whole. For a long line (e.g. minified code) the snippet is windowed
around the match — otherwise a hit past the first 400 chars would be sliced off and the row
would show no highlight. A leading '…' marks a left-truncated window.
"""
if len(line) <= SEARCH_LINE_PREVIEW_CHARS:
col = _utf16_len(line[:start])
return line, col, col + _utf16_len(line[start:end])
win_start = max(0, start - SEARCH_PREVIEW_CONTEXT)
snippet = line[win_start : win_start + SEARCH_LINE_PREVIEW_CHARS]
prefix = "…" if win_start > 0 else ""
text = prefix + snippet
rel_start = len(prefix) + (start - win_start)
rel_end = len(prefix) + min(end - win_start, len(snippet))
return text, _utf16_len(text[:rel_start]), _utf16_len(text[:rel_end])
def _scan_lines(text: str, matcher: "re.Pattern[str]", remaining: int) -> tuple[list[dict[str, Any]], bool]:
matches: list[dict[str, Any]] = []
for line_no, raw_line in enumerate(text.split("\n"), start=1):
# Drop a trailing CR so line-end anchors ('foo$') and previews behave on CRLF files; the CR
# sits after any match, so offsets are unaffected.
line = raw_line[:-1] if raw_line.endswith("\r") else raw_line
for m in matcher.finditer(line):
# Check the cap BEFORE recording: returning True only once we see a match BEYOND the
# limit means a result set with exactly `remaining` matches isn't falsely flagged
# truncated (which would needlessly disable Replace All).
if len(matches) >= remaining:
return matches, True
# col/end are FULL-LINE UTF-16 offsets — the editor jump selects against the whole line.
# preview_col/preview_end index into the (possibly windowed) preview `text` for the row
# highlight; the two differ once a long line is truncated.
full_col = _utf16_len(line[: m.start()])
full_end = full_col + _utf16_len(line[m.start() : m.end()])
preview, preview_col, preview_end = _preview_for_match(line, m.start(), m.end())
matches.append(
{
"line": line_no,
"col": full_col,
"end": full_end,
"text": preview,
"preview_col": preview_col,
"preview_end": preview_end,
"line_truncated": len(line) > SEARCH_LINE_PREVIEW_CHARS,
}
)
return matches, False
def search(
raw_root: str,
query: str,
*,
regex: bool = False,
case_sensitive: bool = False,
whole_word: bool = False,
include: str = "",
exclude: str = "",
max_matches: int = SEARCH_MAX_MATCHES,
max_files: int = SEARCH_MAX_FILES,
) -> dict[str, Any]:
root = _require_directory(raw_root)
matcher = _compile_search_matcher(query, regex=regex, case_sensitive=case_sensitive, whole_word=whole_word)
include_globs = _split_globs(include)
exclude_globs = _split_globs(exclude)
results: list[dict[str, Any]] = []
total_matches = 0
truncated = False
reason: str | None = None
for fpath, rel in _iter_search_files(root, include_globs, exclude_globs):
text, file_mtime = _read_file_text(fpath, lossy=True)
if text is None:
continue
file_matches, overflowed = _scan_lines(text, matcher, max_matches - total_matches)
if not file_matches:
# `remaining` was already 0 and this file still holds a match → a genuine hidden match.
if overflowed:
truncated = True
reason = "matches"
break
continue
if len(results) >= max_files:
# This matching file is the (max_files + 1)th — more files match than we display.
truncated = True
reason = "files"
break
results.append({"path": str(fpath), "rel": rel, "mtime": file_mtime, "match_count": len(file_matches), "matches": file_matches})
total_matches += len(file_matches)
if overflowed:
truncated = True
reason = "matches"
break
return {
"root": str(root),
"query": query,
"results": results,
"total_matches": total_matches,
"total_files": len(results),
"truncated": truncated,
"truncated_reason": reason,
}
def _name_search_hit(path: Path, root: Path) -> dict[str, Any] | None:
"""Build one name-search result row for ``path`` (no-follow stat), or None if it vanished.
Mirrors ``_entry_payload`` but adds the absolute ``path`` and the ``rel`` path from ``root`` so
the UI can render the containing folder and navigate/open the hit directly.
"""
try:
st = path.lstat()
except OSError:
return None
kind = _kind_from_mode(st.st_mode)
size = st.st_size if stat.S_ISREG(st.st_mode) else None
try:
rel = path.relative_to(root).as_posix()
except ValueError:
rel = path.name
return {
"name": path.name,
"kind": kind,
"size": size,
"mtime": _mtime_seconds(st),
"ext": _extension(path) if kind != "dir" else "",
"path": str(path),
"rel": rel,
}
def search_names(
raw_root: str,
query: str,
*,
show_hidden: bool = False,
max_results: int = SEARCH_NAME_MAX_RESULTS,
) -> dict[str, Any]:
"""Recursively find entries under ``root`` whose NAME matches ``query``.
Case-insensitive substring match over both file AND directory names — the file-browser
counterpart to the content ``search`` above (which greps file *contents* and never returns
directories). Prunes the same heavy noise trees (.git / node_modules / build output) so a search
can't stall descending into them, and skips dotfiles/dirs unless ``show_hidden``. Results come
back in walk order (shallow first, a rough relevance signal) and are bounded by ``max_results``;
``truncated`` is set when the cap is hit so the UI can say results were limited.
"""
root = _require_directory(raw_root)
needle = query.strip().lower()
if not needle:
raise FileBrowserError("invalid_query", "Search query is required", 400)
results: list[dict[str, Any]] = []
truncated = False
# os.walk swallows per-directory errors by default, so an unreadable subtree is silently skipped
# (the search keeps going) rather than aborting the whole walk.
for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
# Prune in place: drop noise trees and (unless show_hidden) hidden dirs so os.walk never
# descends into them. The retained dir names are still candidates to MATCH below.
dirnames[:] = sorted(
d for d in dirnames if d not in SEARCH_SKIP_DIRS and (show_hidden or not d.startswith("."))
)
base = Path(dirpath)
# Directories first, then files, each alphabetically — mirrors the listing's grouping.
for name in list(dirnames) + sorted(filenames):
if not show_hidden and name.startswith("."):
continue
if needle not in name.lower():
continue
# Check the cap BEFORE recording (mirrors the content search): flagging truncated only on
# a match BEYOND the cap means a result set of exactly max_results isn't falsely marked
# truncated (which would make the UI claim results were limited when they weren't).
if len(results) >= max_results:
truncated = True
break
hit = _name_search_hit(base / name, root)
if hit is None:
continue
results.append(hit)
if truncated:
break
return {
"ok": True,
"root": str(root),
"query": query,
"results": results,
"truncated": truncated,
"limit": max_results if truncated else None,
}
def _apply_replacement(text: str, matcher: "re.Pattern[str]", replacement: str, *, regex: bool) -> tuple[str, int]:
# Per-line replace so the count and behavior match the per-line search/preview.
# Literal mode treats the replacement verbatim (a lambda avoids backref expansion);
# regex mode keeps Python's \1-style backreferences.
repl: Any = replacement if regex else (lambda _m: replacement)
out: list[str] = []
total = 0
for raw_line in text.split("\n"):
# Match the same CR-stripped content search did, then re-attach the terminator so CRLF files
# keep their line endings.
cr = "\r" if raw_line.endswith("\r") else ""
core = raw_line[: -len(cr)] if cr else raw_line
try:
new_core, count = matcher.subn(repl, core)
except (re.error, IndexError) as exc:
# A bad replacement template (out-of-range \1 or unknown named group \g<x>) raises
# re.error or IndexError; surface a clean 400 instead of a 500.
raise FileBrowserError("invalid_regex", f"Invalid replacement: {exc}", 400) from exc
out.append(new_core + cr)
total += count
return "\n".join(out), total
def _store_undo(token: str, files: dict[str, Any]) -> None:
now = time.monotonic()
size = sum(len(snap["original"].encode("utf-8")) for snap in files.values())
with _UNDO_LOCK:
for stale in [key for key, value in _UNDO_STORE.items() if now - value["created"] > _UNDO_TTL_SECONDS]:
_UNDO_STORE.pop(stale, None)
# Bound the store by BOTH token count and total snapshot bytes so a few large Replace All
# batches can't pin unbounded memory. Evict oldest-first until the new entry fits; a single
# batch larger than the budget still gets stored (it's the user's latest, undoable action)
# but evicts everything else.
def total_bytes() -> int:
return sum(value["bytes"] for value in _UNDO_STORE.values())
while _UNDO_STORE and (len(_UNDO_STORE) >= _UNDO_MAX_TOKENS or total_bytes() + size > _UNDO_MAX_BYTES):
oldest = min(_UNDO_STORE, key=lambda key: _UNDO_STORE[key]["created"])
_UNDO_STORE.pop(oldest, None)
_UNDO_STORE[token] = {"created": now, "files": files, "bytes": size}
def replace(
raw_root: str,
query: str,
replacement: str,
*,
regex: bool = False,
case_sensitive: bool = False,
whole_word: bool = False,
include: str = "",
exclude: str = "",
paths: list[str] | None = None,
expected_mtimes: dict[str, float] | None = None,
max_files: int = SEARCH_MAX_FILES,
) -> dict[str, Any]:
if not isinstance(replacement, str):
raise FileBrowserError("invalid_content", "Replacement must be text", 400)
root = _require_directory(raw_root)
matcher = _compile_search_matcher(query, regex=regex, case_sensitive=case_sensitive, whole_word=whole_word)
pre_skipped: list[dict[str, Any]] = []
# `paths is not None` (not truthiness) marks explicit mode: an empty list means "replace none of
# the shown files" (a no-op), never "walk and rewrite the whole root".
if paths is not None:
candidates: list[tuple[Path, str]] = []
for raw in paths:
try:
resolved = _require_regular_file(raw)
except FileBrowserError as exc:
# A displayed file deleted/renamed/replaced since the search must be reported as
# skipped, not abort the whole batch (the other shown files should still apply).
pre_skipped.append({"path": raw, "rel": raw, "reason": exc.code})
continue
# Search skips symlinks; an explicit path that is now a symlink (e.g. swapped in for a
# shown file after the search) must not be followed, or replace could write through it to
# a target outside the root.
if _expanded_absolute_path(raw).is_symlink():
pre_skipped.append({"path": raw, "rel": raw, "reason": "symlink"})
continue
if resolved != root and root not in resolved.parents:
raise FileBrowserError("invalid_path", "Path is outside the search root", 400)
candidates.append((resolved, resolved.relative_to(root).as_posix()))
else:
# Lazy: iterate the walk and stop at the file cap (the loop breaks) rather than
# materializing every candidate under the root up front.
candidates = _iter_search_files(root, _split_globs(include), _split_globs(exclude))
# In paths mode the caller is replacing the exact files shown in the search results, so a file
# we now can't process (vanished, or not strict-UTF-8 while search saw it via a lossy decode of
# an ASCII match) is reported as skipped rather than silently dropped. In walk mode a None just
# means "not a candidate", so stay quiet.
explicit = paths is not None
changed: list[dict[str, Any]] = []
skipped: list[dict[str, Any]] = list(pre_skipped)
snapshots: dict[str, Any] = {}
total = 0
truncated = False
for fpath, rel in candidates:
if len(changed) >= max_files:
# Stop after the file cap, but tell the caller the batch was bounded so the UI doesn't
# claim the whole root was rewritten.
truncated = True
break
# Capture the mtime BEFORE reading, and hand it to write_file as expected_mtime. A
# concurrent edit landing after this read makes the on-disk mtime diverge, so write_file
# raises a conflict instead of overwriting the other writer with a replacement computed
# from stale bytes.
try:
before_mtime = _mtime_seconds(fpath.stat())
except OSError:
if explicit:
skipped.append({"path": str(fpath), "rel": rel, "reason": "missing"})
continue
# Reject a file that changed between the search the user previewed and this replace, so the
# batch never rewrites matches they never saw (expected_mtimes carries the search-time mtime).
if explicit and expected_mtimes is not None:
expected = expected_mtimes.get(str(fpath))
if expected is not None and abs(before_mtime - float(expected)) > 1e-6:
skipped.append({"path": str(fpath), "rel": rel, "reason": "modified"})
continue
text, _ = _read_file_text(fpath, lossy=False)
if text is None:
if explicit:
skipped.append({"path": str(fpath), "rel": rel, "reason": "unreadable"})
continue
new_text, count = _apply_replacement(text, matcher, replacement, regex=regex)
if count == 0 or new_text == text:
continue
try:
write_file(str(fpath), new_text, expected_mtime=before_mtime)
except FileBrowserError as exc:
# One file failing (read-only, vanished, concurrent edit) must NOT abort the whole batch
# and strip undo from the files already replaced. Record it and keep going; the token
# below still covers every file that did change.
skipped.append({"path": str(fpath), "rel": rel, "reason": exc.code})
continue
snapshots[str(fpath)] = {
"original": text,
"after_sha": hashlib.sha256(new_text.encode("utf-8")).hexdigest(),
}
changed.append({"path": str(fpath), "rel": rel, "replacements": count})
total += count
token: str | None = None
if snapshots:
token = uuid.uuid4().hex
_store_undo(token, snapshots)
return {
"changed": changed,
"skipped": skipped,
"total_replacements": total,
"files_changed": len(changed),
"truncated": truncated,
"undo_token": token,
}
def undo_replace(token: str) -> dict[str, Any]:
with _UNDO_LOCK:
entry = _UNDO_STORE.pop(token, None)
if not entry or time.monotonic() - entry["created"] > _UNDO_TTL_SECONDS:
raise FileBrowserError("undo_unavailable", "Nothing to undo — it expired or was already undone", 404)
restored: list[str] = []
skipped: list[dict[str, str]] = []
for path, snap in entry["files"].items():
target = Path(path)
# Read the mtime from the SAME window as the bytes we verify, and hand it to write_file as
# expected_mtime. Otherwise a re-stat after hashing opens a race where an edit landing
# between the hash check and the write would be silently clobbered by the restore.
try:
before_mtime = _mtime_seconds(target.stat())
current = target.read_bytes()
except FileNotFoundError:
skipped.append({"path": path, "reason": "missing"})
continue
except OSError:
skipped.append({"path": path, "reason": "unreadable"})
continue
# Only revert files still holding exactly what the replace wrote — never
# clobber edits the user (or anything else) made after the replace.
if hashlib.sha256(current).hexdigest() != snap["after_sha"]:
skipped.append({"path": path, "reason": "modified"})
continue
try:
write_file(path, snap["original"], expected_mtime=before_mtime)
except FileBrowserError:
skipped.append({"path": path, "reason": "write_failed"})
continue
restored.append(path)
return {"restored": restored, "skipped": skipped}