← back to Atmos Game
assets/gen/.venv/lib/python3.12/site-packages/filelock/_strict.py
875 lines
from __future__ import annotations
import contextlib
import errno
import os
import secrets
import stat
import sys
import tempfile
import time
from dataclasses import dataclass
from errno import EACCES, EEXIST, ENOENT, ENOSYS, EPERM, ESTALE, EXDEV
from pathlib import Path
from typing import TYPE_CHECKING, Final, Literal, cast
from ._api import BaseFileLock, _canonical, _raise_cleanup_errors
from ._error import SoftFileLockProtocolError
from ._identity import host_name, process_start_token
from ._soft_protocol import STRICT_SOFT_SENTINEL_RECORD
from ._util import ensure_directory_exists, write_all
if TYPE_CHECKING:
from collections.abc import Iterator
StrictSoftFileClaimState = Literal["intent", "held"]
_CLAIM_STATES: Final[frozenset[str]] = frozenset({"intent", "held"})
_COORDINATION_SUFFIX: Final[str] = ".filelock"
_CLAIM_DIRECTORY_NAME: Final[str] = "claims"
_CLAIM_MAGIC: Final[str] = "filelock-strict-v1"
_CLAIM_RECORD_LIMIT: Final[int] = 1024
_CLAIM_NAME_PART_COUNT: Final[int] = 3
_TOKEN_HEX_LENGTH: Final[int] = 32
_PRIVATE_RECORD_MARKER: Final[str] = ".private-v1-"
_PRIVATE_RECORD_SUFFIX: Final[str] = ".tmp"
_PRIVATE_RECORD_RANDOM_HEX_LENGTH: Final[int] = 32
_PRIVATE_RECORD_GRACE: Final[float] = 2.0
_UNLINK_MAX_RETRIES: Final[int] = 10
#: How long a scan waits out a claim held in Windows' delete-pending state before treating it as unreadable.
_CLAIM_READ_GRACE: Final[float] = 0.5
_CLAIM_READ_RETRY: Final[float] = 0.002
#: Windows opens descriptors in text mode by default, which rewrites newlines and truncates a record at a control byte.
#: The claim and sentinel records are exact binary, so every record descriptor must be binary; POSIX ignores the flag.
_O_BINARY: Final[int] = getattr(os, "O_BINARY", 0)
_LEGACY_SENTINEL: Final[bytes] = STRICT_SOFT_SENTINEL_RECORD.encode()
_WINDOWS_HARD_LINK_UNSUPPORTED: Final[frozenset[int]] = frozenset({1, 17, 50})
# Termux/Android CPython ships without os.link (bionic long had only linkat), so the strict backend's whole hard-link
# mechanism is absent there. Probe once and gate every os.link reference on it, so importing filelock still works and
# only an actual StrictSoftFileLock acquire reports the missing capability.
_HAS_LINK: Final[bool] = hasattr(os, "link")
# Probe dir_fd capability once at import. A per-call ``os.unlink in os.supports_dir_fd`` check flips to False the moment
# a test mocks os.unlink, silently diverting the code to a different branch than the one under test.
_OPEN_SUPPORTS_DIR_FD: Final[bool] = os.open in os.supports_dir_fd
_UNLINK_SUPPORTS_DIR_FD: Final[bool] = os.unlink in os.supports_dir_fd
_STAT_SUPPORTS_DIR_FD: Final[bool] = os.stat in os.supports_dir_fd
_LINK_SUPPORTS_DIR_FD: Final[bool] = _HAS_LINK and os.link in os.supports_dir_fd
def _probe_link_follow_symlinks() -> bool:
# os.supports_follow_symlinks lists os.link on PyPy, but its linkat then rejects follow_symlinks=False with EINVAL,
# and Windows raises NotImplementedError for the option outright. Link a throwaway file for real so the answer
# reflects the runtime rather than its advertisement, and treat any failure as "not honored": the option only
# hardens a source this process created with O_EXCL, so skipping it is safe, and a real environment fault surfaces
# when the actual link runs.
if not _HAS_LINK:
return False
try:
with tempfile.TemporaryDirectory() as directory:
source = Path(directory, "probe-source")
source.touch()
os.link(source, Path(directory, "probe-link"), follow_symlinks=False)
except (OSError, NotImplementedError, ValueError):
return False
return True
_LINK_HONORS_FOLLOW_SYMLINKS: Final[bool] = _probe_link_follow_symlinks()
def _probe_hard_link_unsupported_errnos() -> frozenset[int]:
# GraalPy's errno omits ENOTSUP, so importing the name outright breaks every runtime that ships without it. ENOTSUP
# wins wherever it exists, leaving every runtime that names it unchanged. EOPNOTSUPP only stands in for the ones
# that do not, and it approximates rather than matches: the two codes agree on Linux but differ on macOS/BSD and on
# Windows. Where neither exists a runtime that cannot name "operation not supported" cannot raise it either, and
# ENOSYS/EXDEV still classify the link failures it can raise.
not_supported = getattr(errno, "ENOTSUP", getattr(errno, "EOPNOTSUPP", None))
return frozenset({ENOSYS, EXDEV} if not_supported is None else {ENOSYS, EXDEV, not_supported})
_HARD_LINK_UNSUPPORTED_ERRNOS: Final[frozenset[int]] = _probe_hard_link_unsupported_errnos()
class StrictSoftFileLock(BaseFileLock):
"""Portable fail-closed lock based on immutable owner claims."""
_preserve_lock_file_supported: bool = True
_on_acquired_supported: bool = False
#: Age cannot clear a strict claim: expiring one on a clock is the overlap the fail-closed contract exists to rule
#: out, so only force_break() removes it.
_lifetime_supported: bool = False
_lifetime_unsupported_reason: str = "a strict claim is never broken by age, only by force_break()"
#: The claim doorway publishes an intent and a held record per owner, so a shared instance must serialize them.
_serialize_transitions: bool = True
#: Contending processes each publish and rescan several files, so back their retries off across a jittered window
#: rather than let them collide on every poll. Seconds; keeps a waiter responsive once it wins.
_poll_backoff_cap: float = 0.05
def _acquire(self) -> None:
# Resolve once per acquisition, not per poll: a waiter on a relative path must keep publishing into the
# directory it started waiting in even when another thread changes the working directory mid-wait.
if (claim_root := self._context.claim_root) is None:
claim_root = self._context.claim_root = _canonical(self.lock_file)
lock_path = Path(claim_root)
coordination_directory = Path(f"{lock_path}{_COORDINATION_SUFFIX}")
claim_directory = coordination_directory / _CLAIM_DIRECTORY_NAME
ensure_directory_exists(os.fspath(lock_path))
_ensure_protocol_directory(self.lock_file, coordination_directory)
_ensure_protocol_directory(self.lock_file, claim_directory)
if (sentinel_fd := _open_or_create_sentinel(self.lock_file, lock_path, self._open_mode())) is None:
return
try:
sentinel_identity = _file_identity(os.fstat(sentinel_fd))
except BaseException as inspection_error: # preserve inspection and descriptor cleanup errors
try:
os.close(sentinel_fd)
except BaseException as close_error: # ruff:ignore[blind-except] # preserve inspection and descriptor cleanup errors
_raise_cleanup_errors("strict sentinel inspection cleanup failed", inspection_error, close_error)
raise
self._mark_descriptor_pending(sentinel_fd, sentinel_identity)
try:
self._attempt_doorway(claim_directory, sentinel_fd, sentinel_identity)
except BaseException:
if self._context.pending_lock_file_fd == sentinel_fd:
self._discard_doorway(sentinel_fd, sentinel_identity)
raise
def _attempt_doorway(self, claim_directory: Path, sentinel_fd: int, sentinel_identity: tuple[int, int]) -> None:
if _read_existing_claims(self.lock_file, claim_directory):
self._discard_doorway(sentinel_fd, sentinel_identity)
return
token = secrets.token_hex(_TOKEN_HEX_LENGTH // 2)
intent_name = _claim_name("intent", token)
intent_path = str(claim_directory / intent_name)
try:
publication_cleanup_error = _publish_record(intent_path, _claim_record(token), self._open_mode())
except _PrivateRecordReclaimedError:
self._discard_doorway(sentinel_fd, sentinel_identity)
return
except (NotImplementedError, OSError) as error:
_raise_if_hard_links_unsupported(self.lock_file, error)
if isinstance(error, OSError) and error.errno == EEXIST:
self._discard_doorway(sentinel_fd, sentinel_identity)
return
raise
if publication_cleanup_error is not None: # pragma: needs dir-fd
raise publication_cleanup_error
self._context.owner_claim_paths = (intent_path,)
claims = _read_existing_claims(self.lock_file, claim_directory)
if (
not claims
or any(claim.state == "held" for claim in claims)
or min(claim.name for claim in claims) != intent_name
):
self._discard_doorway(sentinel_fd, sentinel_identity)
return
held_name = _claim_name("held", token)
held_path = str(claim_directory / held_name)
try:
link_cleanup_error = _link_no_replace(claim_directory, intent_name, held_name)
except (NotImplementedError, OSError) as error:
_raise_if_hard_links_unsupported(self.lock_file, error)
raise
self._context.owner_claim_paths = (held_path, intent_path)
if link_cleanup_error is not None: # pragma: needs dir-fd
self._context.owner_claim_paths = ()
raise link_cleanup_error
claims = _read_existing_claims(self.lock_file, claim_directory)
if (
not {intent_name, held_name}.issubset(claim.name for claim in claims)
or min(_claim_token_key(claim.name) for claim in claims) != f"v1-{token}.claim"
):
self._discard_doorway(sentinel_fd, sentinel_identity)
return
# Keep the intent claim for the whole hold rather than unlinking it now. The intent has existed, unchanged,
# since this owner published it, so a contender's os.scandir is guaranteed to return it (POSIX only leaves the
# visibility of entries created or removed *during* a scan unspecified). The freshly linked held claim carries
# no such guarantee: a scan that races its creation can miss it. Were the intent removed here, that scan could
# observe neither claim and let a larger-token contender win over this owner. The stable intent is the witness
# that keeps the phase-five min-token decision computed over the true set. Release unlinks both.
self._mark_descriptor_owned(sentinel_fd, sentinel_identity)
@property
def claims(self) -> tuple[StrictSoftFileClaim, ...]:
"""Published claims that block acquisition."""
return _read_existing_claims(self.lock_file, self._claim_directory)
def force_break(self, claim_name: str) -> None:
"""Remove one named claim, allowing overlap if its owner still holds the protected resource."""
_validate_force_break_name(claim_name)
_require_exact_name(self._claim_directory, claim_name)
if (
cleanup_error := _unlink_in_directory(self._claim_directory, claim_name)
) is not None: # pragma: needs dir-fd
raise cleanup_error
def _rollback_failed_acquire(self, acquisition_error: BaseException) -> None:
# _acquire already reconciles a failed doorway through _discard_doorway: it either closes the pending
# descriptor or, when a held claim cannot be removed, commits it as owned so a later release retries and
# raises the cleanup errors. A base rollback would release that owned descriptor again and report each
# failure a second time, so leave the reconciled state alone.
if self.is_locked:
return
super()._rollback_failed_acquire(acquisition_error)
def _reconcile_failed_acquire(self, canonical: str) -> None:
# The acquisition is over, so the next one resolves the working directory again rather than reuse this one's.
if not self.is_locked:
self._context.claim_root = None
super()._reconcile_failed_acquire(canonical)
def _release(self) -> None:
fd = cast("int", self._context.lock_file_fd)
self._context.claim_root = None
remaining, errors = _unlink_owner_paths(self._context.owner_claim_paths)
self._context.owner_claim_paths = tuple(remaining)
if remaining:
_raise_recorded_errors("strict claim release failed", errors)
self._mark_descriptor_released()
try:
self._close_released_fd(fd, default_suppresses=False)
except BaseException as close_error: # ruff:ignore[blind-except] # preserve claim and sentinel cleanup errors
errors.append(close_error)
if errors:
_raise_recorded_errors("strict release cleanup failed", errors)
def _discard_doorway(self, fd: int, identity: tuple[int, int]) -> None:
remaining, errors = _unlink_owner_paths(self._context.owner_claim_paths)
self._context.owner_claim_paths = tuple(remaining)
if remaining:
self._mark_descriptor_owned(fd, identity)
_raise_recorded_errors("strict doorway claim cleanup failed", errors)
self._mark_descriptor_released()
try:
self._close_released_fd(fd, default_suppresses=False)
except BaseException as close_error: # ruff:ignore[blind-except] # preserve claim and sentinel cleanup errors
errors.append(close_error)
if errors:
_raise_recorded_errors("strict doorway cleanup failed", errors)
@property
def _claim_directory(self) -> Path:
if self._context.owner_claim_paths:
return Path(self._context.owner_claim_paths[0]).parent
return Path(f"{_canonical(self.lock_file)}{_COORDINATION_SUFFIX}") / _CLAIM_DIRECTORY_NAME
@dataclass(frozen=True)
class StrictSoftFileClaim:
"""One parsed strict soft-lock claim."""
name: str
state: StrictSoftFileClaimState
token: str
pid: int
hostname: str
#: The owner's process start token, or ``None`` when the platform exposes no proven start time. A strict lock never
#: reclaims a claim on its own, so this identifies the owner for tooling rather than driving any automatic break.
start: int | None = None
class _PrivateRecordReclaimedError(Exception):
pass
def _open_or_create_sentinel(lock_file: str, path: Path, mode: int) -> int | None:
try:
return _open_sentinel(path)
except FileNotFoundError:
pass
except OSError:
return None
_reclaim_sentinel_private_records(path, time.time())
try:
publication_cleanup_error = _publish_record(os.fspath(path), _LEGACY_SENTINEL, mode)
except _PrivateRecordReclaimedError:
return None
except (NotImplementedError, OSError) as error:
_raise_if_hard_links_unsupported(lock_file, error)
if not isinstance(error, OSError) or error.errno != EEXIST:
raise
else:
if publication_cleanup_error is not None: # pragma: needs dir-fd
raise publication_cleanup_error
try:
return _open_sentinel(path)
except OSError:
return None
def _open_sentinel(path: Path) -> int | None:
fd, record = _open_record(path, len(_LEGACY_SENTINEL))
if record == _LEGACY_SENTINEL:
return fd
os.close(fd)
return None
def _read_claims(lock_file: str, directory: Path) -> tuple[StrictSoftFileClaim, ...]:
try:
with os.scandir(directory) as entries:
names = _public_claim_names(directory, entries)
except OSError as error:
reason = f"cannot list claim directory: {error.strerror or type(error).__name__}"
raise SoftFileLockProtocolError(lock_file, None, reason) from error
claims: list[StrictSoftFileClaim] = []
for name in names:
if (name_parts := _parse_claim_name(name)) is None:
raise SoftFileLockProtocolError(lock_file, name, "unknown claim name or protocol version")
if (record := _read_claim_record(lock_file, directory, name)) is not None:
claims.append(_parse_claim(lock_file, name, name_parts, record))
return tuple(claims)
def _read_claim_record(lock_file: str, directory: Path, name: str) -> bytes | None:
# A contended scan can list a claim that is not yet cleanly readable, in two ways that both resolve on a brief
# retry. Windows holds a claim mid-unlink in a delete-pending state that fails an open with EACCES until the unlink
# completes. On NFS, a peer that unlinks its own claim leaves this client's cached filehandle stale, so the next
# open returns ESTALE rather than a clean ENOENT until the lookup revalidates against the server. Retrying re-runs
# the path lookup, which turns the vanished claim into ENOENT (skip) or reads it if it still exists. A genuinely
# unreadable record (a locked-down file, an EIO fault) still fails closed.
deadline = time.monotonic() + _CLAIM_READ_GRACE
delaying = False
while True:
if delaying:
time.sleep(_CLAIM_READ_RETRY)
record, pending = _attempt_claim_read(lock_file, directory, name)
if pending is None:
return record
if time.monotonic() >= deadline:
if pending.errno == ESTALE:
# A stale handle that outlives revalidation is a claim the server no longer has (RFC 1813
# NFS3ERR_STALE): skip it like ENOENT. Skipping a peer's vanished claim can only overcount
# contention, never free a held lock.
return None
reason = f"cannot read claim: {pending.strerror or str(pending) or type(pending).__name__}"
raise SoftFileLockProtocolError(lock_file, name, reason) from pending
delaying = True
def _attempt_claim_read(lock_file: str, directory: Path, name: str) -> tuple[bytes | None, OSError | None]:
# Return the record, or (None, None) when the claim has already gone, or (None, error) for an open the caller may
# retry: a Windows delete-pending EACCES that resolves to a clean removal, or an NFS ESTALE from a peer unlinking
# its own claim out from under this client's cached filehandle. Any other OSError is a real fault and fails closed.
try:
return _read_record(directory / name, _CLAIM_RECORD_LIMIT), None
except FileNotFoundError:
return None, None
except PermissionError as error:
return None, error
except OSError as error:
if error.errno == ESTALE:
return None, error
reason = f"cannot read claim: {error.strerror or str(error) or type(error).__name__}"
raise SoftFileLockProtocolError(lock_file, name, reason) from error
def _public_claim_names(directory: Path, entries: Iterator[os.DirEntry[str]]) -> list[str]:
names: list[str] = []
now = time.time()
for entry in entries:
if not entry.name.startswith("."):
names.append(entry.name)
elif (public_name := _private_public_name(entry.name)) is not None and _parse_claim_name(
public_name
) is not None:
_reclaim_private_record((os.fspath(directory), None), entry.name, now)
return sorted(names)
def _read_existing_claims(lock_file: str, directory: Path) -> tuple[StrictSoftFileClaim, ...]:
if not directory.exists():
return ()
return _read_claims(lock_file, directory)
def _parse_claim(
lock_file: str,
name: str,
name_parts: tuple[StrictSoftFileClaimState, str],
record: bytes,
) -> StrictSoftFileClaim:
try:
magic, token, pid_text, hostname_hex, start_text, trailing = record.decode("ascii").split("\n")
pid = int(pid_text)
start = int(start_text) if start_text else None
hostname = bytes.fromhex(hostname_hex).decode("utf-8")
except (UnicodeDecodeError, ValueError) as error:
raise SoftFileLockProtocolError(lock_file, name, "malformed claim record") from error
if not all((
not trailing,
magic == _CLAIM_MAGIC,
token == name_parts[1],
1 <= pid <= 2**31 - 1,
str(pid) == pid_text,
start is None or (start >= 0 and str(start) == start_text),
hostname.encode().hex() == hostname_hex
and hostname.isprintable()
and not any(character.isspace() for character in hostname),
)):
raise SoftFileLockProtocolError(lock_file, name, "malformed claim record")
return StrictSoftFileClaim(name=name, state=name_parts[0], token=token, pid=pid, hostname=hostname, start=start)
def _parse_claim_name(name: str) -> tuple[StrictSoftFileClaimState, str] | None:
if not name.endswith(".claim"):
return None
parts = name.removesuffix(".claim").split("-")
if len(parts) != _CLAIM_NAME_PART_COUNT or parts[0] not in _CLAIM_STATES or parts[1] != "v1":
return None
token = parts[2]
if len(token) != _TOKEN_HEX_LENGTH or any(character not in "0123456789abcdef" for character in token):
return None
return cast("StrictSoftFileClaimState", parts[0]), token
def _claim_name(state: StrictSoftFileClaimState, token: str) -> str:
return f"{state}-v1-{token}.claim"
def _claim_token_key(name: str) -> str:
return name.removeprefix("held-").removeprefix("intent-")
def _claim_record(token: str) -> bytes:
hostname_hex = host_name().encode().hex()
start = process_start_token(os.getpid())
start_text = "" if start is None else str(start)
return f"{_CLAIM_MAGIC}\n{token}\n{os.getpid()}\n{hostname_hex}\n{start_text}\n".encode("ascii")
def _publish_record(
public_path: str,
record: bytes,
mode: int,
) -> BaseException | None:
directory, public_name = os.path.split(public_path)
directory = directory or os.curdir
private_name = _private_record_name(public_name)
directory_fd = _open_directory(directory) if _OPEN_SUPPORTS_DIR_FD else None
directory_ref = directory, directory_fd
try:
_publish_record_in_directory(directory_ref, (private_name, public_name), mode, record)
except BaseException as publication_error: # preserve publication and directory cleanup errors
try:
if directory_fd is not None: # pragma: needs dir-fd
os.close(directory_fd)
except BaseException as close_error: # ruff:ignore[blind-except] # pragma: needs dir-fd # preserve publication and directory cleanup errors
_raise_cleanup_errors("strict publication directory cleanup failed", publication_error, close_error)
raise
if directory_fd is not None: # pragma: needs dir-fd
try:
os.close(directory_fd)
except BaseException as close_error: # ruff:ignore[blind-except] # caller records the published path before raising
return close_error
return None
def _publish_record_in_directory(
directory_ref: tuple[str, int | None],
names: tuple[str, str],
mode: int,
record: bytes,
) -> None:
flags = os.O_RDWR | os.O_CREAT | os.O_EXCL | _O_BINARY
if (o_nofollow := getattr(os, "O_NOFOLLOW", None)) is not None: # pragma: needs o-nofollow
flags |= o_nofollow
private_fd = _open_relative(directory_ref, names[0], flags, mode)
private_identity: tuple[int, int] | None = None
try:
private_identity = _file_identity(os.fstat(private_fd))
write_all(private_fd, record)
_link_private_record(directory_ref, names, private_identity)
except BaseException as publication_error: # preserve publication and cleanup errors
close_error, unlink_error = _close_and_unlink_private_record(
directory_ref,
names[0],
private_fd,
private_identity,
)
if close_error is not None or unlink_error is not None:
_raise_cleanup_errors(
"strict record publication cleanup failed",
publication_error,
close_error,
unlink_error,
)
raise
close_error, unlink_error = _close_and_unlink_private_record(
directory_ref,
names[0],
private_fd,
private_identity,
)
if close_error is not None or unlink_error is not None:
_raise_record_finalization_errors(close_error, unlink_error)
def _close_and_unlink_private_record(
directory_ref: tuple[str, int | None],
private_name: str,
private_fd: int,
private_identity: tuple[int, int] | None,
) -> tuple[BaseException | None, BaseException | None]:
close_error: BaseException | None = None
try:
os.close(private_fd)
except BaseException as error: # ruff:ignore[blind-except] # returned for grouping with unlink failures
close_error = error
unlink_error: BaseException | None = None
try:
if private_identity is None:
_unlink_relative(directory_ref, private_name)
else:
_unlink_relative_if_identity(directory_ref, private_name, private_identity)
except FileNotFoundError:
pass
except BaseException as error: # ruff:ignore[blind-except] # returned for grouping with close failures
unlink_error = error
return close_error, unlink_error
def _link_private_record(
directory_ref: tuple[str, int | None],
names: tuple[str, str],
private_identity: tuple[int, int],
) -> None:
try:
_link_relative(directory_ref, *names)
except FileNotFoundError as error:
if _relative_identity(directory_ref, names[0]) is not None:
raise
msg = "private publication record was reclaimed"
raise _PrivateRecordReclaimedError(msg) from error
if _relative_identity(directory_ref, names[1]) == private_identity:
return
msg_0 = "private publication record was replaced"
raise _PrivateRecordReclaimedError(msg_0)
def _raise_record_finalization_errors(
close_error: BaseException | None,
unlink_error: BaseException | None,
) -> None:
errors = [error for error in (close_error, unlink_error) if error is not None]
if len(errors) > 1:
_raise_cleanup_errors("strict record finalization failed", errors[0], *errors[1:])
raise errors[0]
def _private_record_name(public_name: str) -> str:
return f".{public_name}{_PRIVATE_RECORD_MARKER}{secrets.token_hex(_PRIVATE_RECORD_RANDOM_HEX_LENGTH // 2)}.tmp"
def _private_public_name(private_name: str) -> str | None:
if not private_name.startswith(".") or not private_name.endswith(_PRIVATE_RECORD_SUFFIX):
return None
public_name, marker, random_hex = private_name[1 : -len(_PRIVATE_RECORD_SUFFIX)].rpartition(_PRIVATE_RECORD_MARKER)
if (
marker != _PRIVATE_RECORD_MARKER
or len(random_hex) != _PRIVATE_RECORD_RANDOM_HEX_LENGTH
or any(character not in "0123456789abcdef" for character in random_hex)
):
return None
return public_name
def _reclaim_sentinel_private_records(path: Path, now: float) -> None:
directory_ref = os.fspath(path.parent), None
with os.scandir(path.parent) as entries:
for entry in entries:
if _private_public_name(entry.name) == path.name:
_reclaim_private_record(directory_ref, entry.name, now)
def _reclaim_private_record(directory_ref: tuple[str, int | None], private_name: str, now: float) -> None:
directory, directory_fd = directory_ref
try:
private_stat = (
os.stat(private_name, dir_fd=directory_fd, follow_symlinks=False)
if directory_fd is not None and _STAT_SUPPORTS_DIR_FD
else Path(directory, private_name).lstat()
)
except FileNotFoundError:
return
if not stat.S_ISREG(private_stat.st_mode):
msg = f"{Path(directory, private_name)} is not a regular private record"
raise OSError(msg)
if private_stat.st_nlink == 1 and now - private_stat.st_mtime < _PRIVATE_RECORD_GRACE:
return
try:
_unlink_private_record_once(directory_ref, private_name)
except FileNotFoundError:
pass
except OSError as error:
if error.errno not in {EACCES, EPERM}:
raise
def _unlink_private_record_once(directory_ref: tuple[str, int | None], private_name: str) -> None:
directory, directory_fd = directory_ref
if (
directory_fd is not None and _UNLINK_SUPPORTS_DIR_FD
): # pragma: no cover # callers always pass directory_fd=None
os.unlink(private_name, dir_fd=directory_fd)
else:
Path(directory, private_name).unlink()
def _relative_identity(directory_ref: tuple[str, int | None], name: str) -> tuple[int, int] | None:
directory, directory_fd = directory_ref
try:
if directory_fd is not None and _STAT_SUPPORTS_DIR_FD: # pragma: needs dir-fd
path_stat = os.stat(name, dir_fd=directory_fd, follow_symlinks=False)
else: # pragma: win32 cover
path_stat = Path(directory, name).lstat()
except FileNotFoundError:
return None
return _file_identity(path_stat)
def _unlink_relative_if_identity(
directory_ref: tuple[str, int | None],
name: str,
identity: tuple[int, int],
) -> None:
if _relative_identity(directory_ref, name) == identity:
with contextlib.suppress(FileNotFoundError):
_unlink_relative(directory_ref, name)
def _open_relative(directory_ref: tuple[str, int | None], name: str, flags: int, mode: int) -> int:
directory, directory_fd = directory_ref
return (
os.open(name, flags, mode, dir_fd=directory_fd)
if directory_fd is not None
else os.open(Path(directory, name), flags, mode)
)
def _link_relative(directory_ref: tuple[str, int | None], source_name: str, destination_name: str) -> None:
directory, directory_fd = directory_ref
if directory_fd is not None and _LINK_SUPPORTS_DIR_FD: # pragma: needs dir-fd
_link_no_follow(source_name, destination_name, src_dir_fd=directory_fd, dst_dir_fd=directory_fd)
return
_link_no_follow(Path(directory, source_name), Path(directory, destination_name)) # pragma: win32 cover
def _link_no_follow(
source: str | Path,
destination: str | Path,
*,
src_dir_fd: int | None = None,
dst_dir_fd: int | None = None,
) -> None:
if not _HAS_LINK:
# No os.link at all (Termux/Android): report it as unsupported like a filesystem that refuses hard links, so
# the acquire path raises SoftFileLockProtocolError instead of a bare AttributeError.
msg = "os.link is unavailable on this platform"
raise NotImplementedError(msg)
# The source is a private record this process created with O_CREAT | O_EXCL, so follow_symlinks guards nothing an
# attacker can reach. Pass the option only when the runtime honors it: PyPy advertises it through
# os.supports_follow_symlinks yet its linkat rejects it with EINVAL, so probe once rather than trust the set.
if _LINK_HONORS_FOLLOW_SYMLINKS:
os.link(source, destination, src_dir_fd=src_dir_fd, dst_dir_fd=dst_dir_fd, follow_symlinks=False)
else: # pragma: lacks link-follow-symlinks
os.link(source, destination, src_dir_fd=src_dir_fd, dst_dir_fd=dst_dir_fd)
def _unlink_relative(directory_ref: tuple[str, int | None], name: str) -> None:
directory, directory_fd = directory_ref
if directory_fd is not None and _UNLINK_SUPPORTS_DIR_FD: # pragma: needs dir-fd
os.unlink(name, dir_fd=directory_fd)
elif sys.platform == "win32": # pragma: win32 cover
_unlink_in_directory(Path(directory), name)
else:
Path(directory, name).unlink() # pragma: win32 no cover
def _link_no_replace(directory: Path, source_name: str, destination_name: str) -> BaseException | None:
if _LINK_SUPPORTS_DIR_FD: # pragma: needs dir-fd
directory_fd = _open_directory(str(directory))
try:
_link_no_follow(source_name, destination_name, src_dir_fd=directory_fd, dst_dir_fd=directory_fd)
except BaseException as link_error: # preserve link and directory cleanup errors
try:
os.close(directory_fd)
except BaseException as close_error: # ruff:ignore[blind-except] # preserve link and directory cleanup errors
_raise_cleanup_errors("strict link directory cleanup failed", link_error, close_error)
raise
try:
os.close(directory_fd)
except BaseException as close_error: # ruff:ignore[blind-except] # caller records the held path before raising
return close_error
return None
_link_no_follow(directory / source_name, directory / destination_name) # pragma: win32 cover
return None # pragma: win32 cover
def _unlink_owner_path(path: str) -> BaseException | None:
directory, name = os.path.split(path)
return _unlink_in_directory(Path(directory or os.curdir), name)
def _unlink_owner_paths(paths: tuple[str, ...]) -> tuple[list[str], list[BaseException]]:
results = [(path, _unlink_owner_path_result(path)) for path in paths]
return [path for path, (removed, _) in results if not removed], [
error for _, (_, error) in results if error is not None
]
def _unlink_owner_path_result(path: str) -> tuple[bool, BaseException | None]:
try:
cleanup_error = _unlink_owner_path(path)
except FileNotFoundError:
return True, None
except BaseException as error: # ruff:ignore[blind-except] # keep ownership when unlink did not commit
return False, error
return True, cleanup_error
def _raise_recorded_errors(message: str, errors: list[BaseException]) -> None:
if len(errors) > 1:
_raise_cleanup_errors(message, errors[0], *errors[1:])
raise errors[0]
def _unlink_in_directory(directory: Path, name: str) -> BaseException | None:
if _UNLINK_SUPPORTS_DIR_FD: # pragma: needs dir-fd
directory_fd = _open_directory(str(directory))
try:
os.unlink(name, dir_fd=directory_fd)
except BaseException as unlink_error: # preserve unlink and directory cleanup errors
try:
os.close(directory_fd)
except BaseException as close_error: # ruff:ignore[blind-except] # preserve unlink and directory cleanup errors
_raise_cleanup_errors("strict unlink directory cleanup failed", unlink_error, close_error)
raise
try:
os.close(directory_fd)
except BaseException as close_error: # ruff:ignore[blind-except] # caller commits the removed path before raising
return close_error
return None
if sys.platform != "win32": # pragma: win32 no cover
Path(directory / name).unlink()
return None
retry_delay = 0.001 # pragma: win32 cover
for attempt in range(_UNLINK_MAX_RETRIES): # pragma: win32 cover
if (error := _unlink_error(directory / name)) is None:
return None
if error.errno not in {EACCES, EPERM} or attempt == _UNLINK_MAX_RETRIES - 1:
raise error
time.sleep(retry_delay)
retry_delay *= 2
return None # pragma: no cover # the final retry returns or raises
def _unlink_error(path: Path) -> OSError | None: # pragma: win32 cover
try:
path.unlink()
except OSError as error:
return error
return None
def _open_directory(directory: str) -> int: # pragma: needs dir-fd
return os.open(
directory,
os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
)
def _read_record(path: Path, limit: int) -> bytes:
fd, record = _open_record(path, limit)
os.close(fd)
return record
def _open_record(path: Path, limit: int) -> tuple[int, bytes]:
path_stat = path.lstat()
if not stat.S_ISREG(path_stat.st_mode):
msg = f"{path} is not a regular file"
raise OSError(msg)
flags = os.O_RDONLY | _O_BINARY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
fd = os.open(path, flags)
try:
record = _read_opened_record(fd, path, path_stat, limit)
except BaseException as read_error: # preserve read and descriptor cleanup errors
try:
os.close(fd)
except BaseException as close_error: # ruff:ignore[blind-except] # preserve read and descriptor cleanup errors
_raise_cleanup_errors("strict record read cleanup failed", read_error, close_error)
raise
return fd, record
def _read_opened_record(fd: int, path: Path, path_stat: os.stat_result, limit: int) -> bytes:
opened_stat = os.fstat(fd)
if not stat.S_ISREG(opened_stat.st_mode):
msg = f"{path} is not a regular file"
raise OSError(msg)
if _file_identity(opened_stat) != _file_identity(path_stat):
msg = f"{path} changed while opening"
raise OSError(msg)
record = os.read(fd, limit + 1)
if len(record) > limit:
msg = f"{path} exceeds {limit} bytes"
raise OSError(msg)
return record
def _ensure_protocol_directory(lock_file: str, directory: Path) -> None:
try:
directory.mkdir()
except FileExistsError:
try:
mode = directory.lstat().st_mode
except OSError as error:
raise SoftFileLockProtocolError(lock_file, None, f"cannot inspect {directory}") from error
if stat.S_ISDIR(mode) and not stat.S_ISLNK(mode):
return
raise SoftFileLockProtocolError(lock_file, None, f"{directory} is not a real directory") from None
def _validate_force_break_name(name: str) -> None:
invalid_component = not name or name.startswith(".") or name in {os.curdir, os.pardir}
if invalid_component or any(separator in name for separator in ("/", "\\", "\x00")):
msg = "claim_name must be one public claim basename"
raise ValueError(msg)
def _require_exact_name(directory: Path, name: str) -> None:
with os.scandir(directory) as entries:
if not any(entry.name == name for entry in entries):
raise FileNotFoundError(ENOENT, os.strerror(ENOENT), name)
def _raise_if_hard_links_unsupported(lock_file: str, error: NotImplementedError | OSError) -> None:
unsupported = (
isinstance(error, NotImplementedError)
or error.errno in _HARD_LINK_UNSUPPORTED_ERRNOS
or (getattr(error, "winerror", None) in _WINDOWS_HARD_LINK_UNSUPPORTED)
)
if unsupported:
reason = "filesystem does not support atomic no-replace hard-link publication"
raise SoftFileLockProtocolError(lock_file, None, reason) from error
def _file_identity(st: os.stat_result) -> tuple[int, int]:
return st.st_dev, st.st_ino
__all__ = [
"StrictSoftFileClaim",
"StrictSoftFileClaimState",
"StrictSoftFileLock",
]