servatus 0.0.1__py3-none-any.whl

servatus/__init__.py

@@ -0,0 +1,26 @@
+from ._errors import (
+    CrossDevicePublication,
+    DestinationExists,
+    PublicationError,
+    ServatusError,
+    UnsafePublication,
+    UnsupportedPlatform,
+    WorkConflict,
+    WorkspaceBusy,
+)
+from ._workspace import Draft, Publication, Workspace, publish
+
+__all__ = [
+    "CrossDevicePublication",
+    "DestinationExists",
+    "Draft",
+    "Publication",
+    "PublicationError",
+    "ServatusError",
+    "UnsafePublication",
+    "UnsupportedPlatform",
+    "WorkConflict",
+    "Workspace",
+    "WorkspaceBusy",
+    "publish",
+]

servatus/_errors.py

@@ -0,0 +1,30 @@
+class ServatusError(Exception):
+    """Base class for Servatus contract failures."""
+
+
+class PublicationError(ServatusError):
+    """A draft could not be safely published."""
+
+
+class DestinationExists(PublicationError):
+    """The requested destination or draft entry already exists."""
+
+
+class CrossDevicePublication(PublicationError):
+    """Publication would cross a filesystem boundary."""
+
+
+class UnsafePublication(PublicationError):
+    """A path or filesystem entry violates the publication contract."""
+
+
+class UnsupportedPlatform(PublicationError):
+    """The platform cannot provide an atomic no-replace commit."""
+
+
+class WorkConflict(ServatusError):
+    """Existing private work is bound to another identity."""
+
+
+class WorkspaceBusy(ServatusError):
+    """Another writer currently owns the workspace."""

servatus/_posix.py

@@ -0,0 +1,316 @@
+from __future__ import annotations
+
+import ctypes
+import errno
+import os
+import shutil
+import stat
+import sys
+from collections.abc import Callable
+from contextlib import suppress
+from pathlib import Path
+
+from ._errors import (
+    CrossDevicePublication,
+    DestinationExists,
+    PublicationError,
+    UnsafePublication,
+    UnsupportedPlatform,
+)
+
+_RENAME_NOREPLACE = 1
+_RENAME_EXCL = 0x00000004
+_DIRECTORY_FLAGS = os.O_RDONLY | os.O_DIRECTORY | os.O_CLOEXEC | os.O_NOFOLLOW
+_FILE_FLAGS = os.O_RDONLY | os.O_CLOEXEC | os.O_NOFOLLOW | os.O_NONBLOCK
+
+
+def require_supported_platform() -> None:
+    if not (sys.platform.startswith("linux") or sys.platform == "darwin"):
+        raise UnsupportedPlatform(f"unsupported platform: {sys.platform}")
+
+
+def normalize_destination(destination: Path) -> tuple[Path, str]:
+    raw = Path(destination)
+    reject_nul_path(raw)
+    if not raw.name or raw.name in {".", ".."}:
+        raise UnsafePublication("destination must name a directory inside an existing parent")
+    try:
+        parent = raw.parent.resolve(strict=True)
+    except (OSError, ValueError) as error:
+        raise UnsafePublication("destination parent does not exist") from error
+    if not parent.is_dir():
+        raise UnsafePublication("destination parent is not a directory")
+    return parent, raw.name
+
+
+def open_directory(path: Path) -> int:
+    reject_nul_path(path)
+    try:
+        return os.open(path, _DIRECTORY_FLAGS)
+    except OSError as error:
+        raise UnsafePublication(f"unsafe directory: {path}") from error
+
+
+def open_directory_at(parent_fd: int, name: str) -> int:
+    validate_leaf(name)
+    try:
+        descriptor = os.open(name, _DIRECTORY_FLAGS, dir_fd=parent_fd)
+    except OSError as error:
+        raise UnsafePublication(f"unsafe directory entry: {name}") from error
+    parent_device = os.fstat(parent_fd).st_dev
+    if os.fstat(descriptor).st_dev != parent_device:
+        os.close(descriptor)
+        raise CrossDevicePublication(f"directory crosses a filesystem boundary: {name}")
+    return descriptor
+
+
+def same_entry(left: os.stat_result, right: os.stat_result) -> bool:
+    return left.st_dev == right.st_dev and left.st_ino == right.st_ino
+
+
+def ensure_entry(parent_fd: int, name: str, expected: os.stat_result) -> None:
+    validate_leaf(name)
+    try:
+        current = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    except OSError as error:
+        raise UnsafePublication(f"filesystem entry disappeared: {name}") from error
+    if not same_entry(current, expected):
+        raise UnsafePublication(f"filesystem entry changed during publication: {name}")
+
+
+def ensure_directory_path(path: Path, descriptor: int) -> None:
+    reject_nul_path(path)
+    try:
+        current = path.stat(follow_symlinks=False)
+    except OSError as error:
+        raise UnsafePublication(f"publication parent disappeared: {path}") from error
+    if not stat.S_ISDIR(current.st_mode) or not same_entry(current, os.fstat(descriptor)):
+        raise UnsafePublication(f"publication parent changed: {path}")
+
+
+def make_directory_at(parent_fd: int, name: str) -> tuple[int, os.stat_result]:
+    validate_leaf(name)
+    with suppress(FileExistsError):
+        os.mkdir(name, mode=0o700, dir_fd=parent_fd)
+    descriptor = open_directory_at(parent_fd, name)
+    return descriptor, os.fstat(descriptor)
+
+
+def make_unique_stage(parent_fd: int, prefix: str) -> tuple[str, int, os.stat_result]:
+    validate_leaf(prefix)
+    for _ in range(128):
+        name = f"{prefix}{os.urandom(12).hex()}"
+        try:
+            os.mkdir(name, mode=0o700, dir_fd=parent_fd)
+        except FileExistsError:
+            continue
+        entry = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+        descriptor = -1
+        try:
+            descriptor = open_directory_at(parent_fd, name)
+            entry = os.fstat(descriptor)
+            sync_descriptor(parent_fd)
+        except BaseException as error:
+            cleanup_after_failure(parent_fd, name, entry, error)
+            if descriptor >= 0:
+                os.close(descriptor)
+            raise
+        return name, descriptor, entry
+    raise PublicationError("could not allocate a unique publication stage")
+
+
+def sync_descriptor(descriptor: int) -> None:
+    os.fsync(descriptor)
+
+
+def sync_tree(descriptor: int, device: int) -> None:
+    for name in sorted(os.listdir(descriptor)):
+        try:
+            entry = os.stat(name, dir_fd=descriptor, follow_symlinks=False)
+        except OSError as error:
+            raise UnsafePublication(f"draft entry disappeared: {name}") from error
+        if entry.st_dev != device:
+            raise CrossDevicePublication(f"draft entry crosses a filesystem boundary: {name}")
+        if stat.S_ISREG(entry.st_mode):
+            _sync_regular_file(descriptor, name, entry)
+        elif stat.S_ISDIR(entry.st_mode):
+            child = open_directory_at(descriptor, name)
+            try:
+                sync_tree(child, device)
+            finally:
+                os.close(child)
+            ensure_entry(descriptor, name, entry)
+        else:
+            raise UnsafePublication(f"draft contains a symlink or special file: {name}")
+    sync_descriptor(descriptor)
+
+
+def _sync_regular_file(parent_fd: int, name: str, expected: os.stat_result) -> None:
+    try:
+        descriptor = os.open(name, _FILE_FLAGS, dir_fd=parent_fd)
+    except OSError as error:
+        raise UnsafePublication(f"unsafe regular file: {name}") from error
+    try:
+        opened = os.fstat(descriptor)
+        if not stat.S_ISREG(opened.st_mode) or not same_entry(opened, expected):
+            raise UnsafePublication(f"draft file changed during publication: {name}")
+        sync_descriptor(descriptor)
+        synced = os.fstat(descriptor)
+        current = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+        if not same_entry(synced, current):
+            raise UnsafePublication(f"draft file changed during publication: {name}")
+        if (opened.st_size, opened.st_mtime_ns) != (synced.st_size, synced.st_mtime_ns):
+            raise UnsafePublication(f"draft file was modified during publication: {name}")
+    finally:
+        os.close(descriptor)
+
+
+def reject_nul_path(path: Path) -> None:
+    if "\0" in os.fspath(path):
+        raise UnsafePublication(f"path contains an embedded NUL: {path!r}")
+
+
+def validate_leaf(name: str) -> None:
+    if not name or name in {".", ".."} or "/" in name or "\0" in name:
+        raise UnsafePublication(f"unsafe filesystem leaf: {name!r}")
+
+
+def commit_noreplace(parent_fd: int, source: str, destination: str) -> None:
+    require_supported_platform()
+    validate_leaf(source)
+    validate_leaf(destination)
+    if sys.platform.startswith("linux"):
+        _linux_rename_noreplace(parent_fd, source, destination)
+    else:
+        _macos_rename_noreplace(parent_fd, source, destination)
+
+
+def _linux_rename_noreplace(parent_fd: int, source: str, destination: str) -> None:
+    library = ctypes.CDLL(None, use_errno=True)
+    try:
+        renameat2 = library.renameat2
+    except AttributeError as error:
+        raise UnsupportedPlatform("libc does not expose renameat2") from error
+    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(
+        parent_fd,
+        os.fsencode(source),
+        parent_fd,
+        os.fsencode(destination),
+        _RENAME_NOREPLACE,
+    )
+    if result != 0:
+        _raise_rename_error(ctypes.get_errno())
+
+
+def _macos_rename_noreplace(parent_fd: int, source: str, destination: str) -> None:
+    library = ctypes.CDLL(None, use_errno=True)
+    try:
+        renameatx_np = library.renameatx_np
+    except AttributeError as error:
+        raise UnsupportedPlatform("libc does not expose renameatx_np") from error
+    renameatx_np.argtypes = [
+        ctypes.c_int,
+        ctypes.c_char_p,
+        ctypes.c_int,
+        ctypes.c_char_p,
+        ctypes.c_uint,
+    ]
+    renameatx_np.restype = ctypes.c_int
+    result = renameatx_np(
+        parent_fd,
+        os.fsencode(source),
+        parent_fd,
+        os.fsencode(destination),
+        _RENAME_EXCL,
+    )
+    if result != 0:
+        _raise_rename_error(ctypes.get_errno())
+
+
+def _raise_rename_error(error_number: int) -> None:
+    if error_number in {errno.EEXIST, errno.ENOTEMPTY}:
+        raise DestinationExists("publication destination already exists")
+    if error_number == errno.EXDEV:
+        raise CrossDevicePublication("publication commit crosses a filesystem boundary")
+    if error_number in {errno.EINVAL, errno.ENOSYS, errno.EOPNOTSUPP}:
+        raise UnsupportedPlatform("filesystem does not support atomic no-replace rename")
+    raise OSError(error_number, os.strerror(error_number))
+
+
+def remove_tree_at(parent_fd: int, name: str, expected: os.stat_result) -> None:
+    ensure_entry(parent_fd, name, expected)
+    if not shutil.rmtree.avoids_symlink_attacks:
+        raise UnsupportedPlatform("safe directory removal is unavailable")
+    shutil.rmtree(name, dir_fd=parent_fd)
+    sync_descriptor(parent_fd)
+
+
+def remove_file_at(parent_fd: int, name: str, expected: os.stat_result) -> None:
+    ensure_entry(parent_fd, name, expected)
+    if not stat.S_ISREG(expected.st_mode):
+        raise UnsafePublication(f"cleanup target is not a regular file: {name}")
+    os.unlink(name, dir_fd=parent_fd)
+    sync_descriptor(parent_fd)
+
+
+def cleanup_after_failure(
+    parent_fd: int,
+    name: str,
+    expected: os.stat_result,
+    error: BaseException,
+) -> None:
+    try:
+        remove_tree_at(parent_fd, name, expected)
+    except Exception as cleanup_error:
+        error.add_note(f"Servatus could not remove failed stage: {cleanup_error}")
+
+
+def publication_attempt(
+    destination: Path,
+    build: Callable[[Path, int, int], None],
+) -> Path:
+    require_supported_platform()
+    parent, destination_name = normalize_destination(destination)
+    parent_fd = open_directory(parent)
+    try:
+        return publication_attempt_at(parent, parent_fd, destination_name, build)
+    finally:
+        os.close(parent_fd)
+
+
+def publication_attempt_at(
+    parent: Path,
+    parent_fd: int,
+    destination_name: str,
+    build: Callable[[Path, int, int], None],
+) -> Path:
+    ensure_directory_path(parent, parent_fd)
+    stage_name = ""
+    stage_fd = -1
+    stage_entry: os.stat_result | None = None
+    try:
+        stage_name, stage_fd, stage_entry = make_unique_stage(parent_fd, ".servatus-stage-")
+        build(parent / stage_name, stage_fd, stage_entry.st_dev)
+        ensure_entry(parent_fd, stage_name, stage_entry)
+        sync_tree(stage_fd, stage_entry.st_dev)
+        ensure_entry(parent_fd, stage_name, stage_entry)
+        ensure_directory_path(parent, parent_fd)
+        commit_noreplace(parent_fd, stage_name, destination_name)
+        sync_descriptor(parent_fd)
+        return parent / destination_name
+    except BaseException as error:
+        if stage_name and stage_entry is not None:
+            cleanup_after_failure(parent_fd, stage_name, stage_entry, error)
+        raise
+    finally:
+        if stage_fd >= 0:
+            with suppress(OSError):
+                os.close(stage_fd)

servatus/_workspace.py

@@ -0,0 +1,306 @@
+from __future__ import annotations
+
+import errno
+import fcntl
+import hashlib
+import os
+import stat
+from collections.abc import Callable
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from . import _posix
+from ._errors import (
+    CrossDevicePublication,
+    DestinationExists,
+    UnsafePublication,
+    WorkConflict,
+    WorkspaceBusy,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Publication:
+    destination: Path
+    cleanup_pending: bool
+
+
+class Draft:
+    def __init__(self, path: Path, descriptor: int, device: int) -> None:
+        self._path = path
+        self._descriptor = descriptor
+        self._device = device
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    def link(self, source: Path, destination: str | PurePosixPath) -> None:
+        components = _safe_components(destination)
+        source_path = Path(source)
+        _posix.reject_nul_path(source_path)
+        try:
+            source_entry = source_path.stat(follow_symlinks=False)
+        except OSError as error:
+            raise UnsafePublication(f"hard-link source is unavailable: {source_path}") from error
+        if not stat.S_ISREG(source_entry.st_mode):
+            raise UnsafePublication(f"hard-link source is not a regular file: {source_path}")
+        try:
+            source_fd = os.open(
+                source_path,
+                os.O_RDONLY | os.O_CLOEXEC | os.O_NOFOLLOW | os.O_NONBLOCK,
+            )
+        except OSError as error:
+            raise UnsafePublication(f"unsafe hard-link source: {source_path}") from error
+        try:
+            opened_source = os.fstat(source_fd)
+            if not stat.S_ISREG(opened_source.st_mode) or not _posix.same_entry(
+                opened_source, source_entry
+            ):
+                raise UnsafePublication(f"hard-link source changed: {source_path}")
+            if opened_source.st_dev != self._device:
+                raise CrossDevicePublication(
+                    f"hard-link source is on another filesystem: {source_path}"
+                )
+            self._link_open_source(source_path, opened_source, components)
+        finally:
+            os.close(source_fd)
+
+    def _link_open_source(
+        self,
+        source: Path,
+        source_entry: os.stat_result,
+        components: tuple[str, ...],
+    ) -> None:
+        current_fd = os.dup(self._descriptor)
+        try:
+            for component in components[:-1]:
+                with suppress(FileExistsError):
+                    os.mkdir(component, mode=0o700, dir_fd=current_fd)
+                child_fd = _posix.open_directory_at(current_fd, component)
+                os.close(current_fd)
+                current_fd = child_fd
+            leaf = components[-1]
+            try:
+                os.link(source, leaf, dst_dir_fd=current_fd, follow_symlinks=False)
+            except FileExistsError as error:
+                raise DestinationExists(
+                    f"draft path already exists: {PurePosixPath(*components)}"
+                ) from error
+            except OSError as error:
+                if error.errno == errno.EXDEV:
+                    raise CrossDevicePublication(
+                        f"hard-link source is on another filesystem: {source}"
+                    ) from error
+                raise
+            linked = os.stat(leaf, dir_fd=current_fd, follow_symlinks=False)
+            if not stat.S_ISREG(linked.st_mode) or not _posix.same_entry(linked, source_entry):
+                with suppress(OSError):
+                    os.unlink(leaf, dir_fd=current_fd)
+                raise UnsafePublication(f"hard-link source changed: {source}")
+        finally:
+            os.close(current_fd)
+
+
+def _safe_components(destination: str | PurePosixPath) -> tuple[str, ...]:
+    if "\0" in os.fspath(destination):
+        raise UnsafePublication(f"draft path contains an embedded NUL: {destination!r}")
+    path = PurePosixPath(destination)
+    if path.is_absolute() or not path.parts or any(part in {"", ".", ".."} for part in path.parts):
+        raise UnsafePublication(f"draft path must be safe and relative: {destination}")
+    return path.parts
+
+
+def _build_draft(build: Callable[[Draft], None]) -> Callable[[Path, int, int], None]:
+    def run(path: Path, descriptor: int, device: int) -> None:
+        build(Draft(path, descriptor, device))
+
+    return run
+
+
+def publish(destination: Path, build: Callable[[Draft], None]) -> Publication:
+    committed = _posix.publication_attempt(destination, _build_draft(build))
+    return Publication(committed, cleanup_pending=False)
+
+
+class Workspace:
+    def __init__(self, destination: Path, *, identity: bytes) -> None:
+        parent, destination_name = _posix.normalize_destination(destination)
+        destination_key = hashlib.sha256(os.fsencode(destination_name)).hexdigest()[:24]
+        self._destination = parent / destination_name
+        self._parent = parent
+        self._parent_fd = -1
+        self._container_fd = -1
+        self._work_fd = -1
+        self._lock_fd = -1
+        self._container_entry: os.stat_result | None = None
+        self._container_name = f".servatus-{destination_key}.work"
+        self._identity = hashlib.sha256(identity).hexdigest().encode("ascii") + b"\n"
+        self._entered = False
+        self._published = False
+
+    def __enter__(self) -> Workspace:
+        if self._entered:
+            raise RuntimeError("workspace is already entered")
+        _posix.require_supported_platform()
+        self._parent_fd = _posix.open_directory(self._parent)
+        try:
+            self._container_fd, self._container_entry = _posix.make_directory_at(
+                self._parent_fd, self._container_name
+            )
+            self._lock_fd = self._open_lock()
+            try:
+                fcntl.flock(self._lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError as error:
+                raise WorkspaceBusy(f"workspace is already locked: {self._destination}") from error
+            self._bind_identity()
+            self._work_fd, _ = _posix.make_directory_at(self._container_fd, "work")
+            _posix.sync_descriptor(self._container_fd)
+        except BaseException:
+            self._close()
+            raise
+        self._entered = True
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self._close()
+
+    @property
+    def path(self) -> Path:
+        return self._parent / self._container_name / "work"
+
+    def publish(self, build: Callable[[Draft], None]) -> Publication:
+        if not self._entered or self._parent_fd < 0 or self._container_entry is None:
+            raise RuntimeError("workspace must be entered before publication")
+        if self._published:
+            raise RuntimeError("workspace has already published")
+        _posix.ensure_entry(self._parent_fd, self._container_name, self._container_entry)
+        self._verify_identity()
+        committed = _posix.publication_attempt_at(
+            self._parent,
+            self._parent_fd,
+            self._destination.name,
+            _build_draft(build),
+        )
+        cleanup_pending = False
+        try:
+            _cleanup_workspace(
+                self._parent_fd,
+                self._container_name,
+                self._container_entry,
+            )
+        except Exception:
+            cleanup_pending = True
+        self._published = True
+        return Publication(committed, cleanup_pending=cleanup_pending)
+
+    def _open_lock(self) -> int:
+        assert self._container_fd >= 0
+        try:
+            descriptor = os.open(
+                ".lock",
+                os.O_RDWR | os.O_CREAT | os.O_CLOEXEC | os.O_NOFOLLOW,
+                0o600,
+                dir_fd=self._container_fd,
+            )
+        except OSError as error:
+            raise UnsafePublication("workspace lock is unsafe") from error
+        lock_entry = os.fstat(descriptor)
+        if not stat.S_ISREG(lock_entry.st_mode):
+            os.close(descriptor)
+            raise UnsafePublication("workspace lock is not a regular file")
+        return descriptor
+
+    def _bind_identity(self) -> None:
+        assert self._container_fd >= 0
+        try:
+            os.stat(".identity", dir_fd=self._container_fd, follow_symlinks=False)
+        except FileNotFoundError:
+            self._initialize_identity()
+        else:
+            self._verify_identity()
+
+    def _initialize_identity(self) -> None:
+        assert self._container_fd >= 0
+        stage_name = f".identity-{os.urandom(12).hex()}.tmp"
+        descriptor = -1
+        stage_entry: os.stat_result | None = None
+        try:
+            descriptor = os.open(
+                stage_name,
+                os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_CLOEXEC | os.O_NOFOLLOW,
+                0o600,
+                dir_fd=self._container_fd,
+            )
+            stage_entry = os.fstat(descriptor)
+            view = memoryview(self._identity)
+            while view:
+                written = os.write(descriptor, view)
+                view = view[written:]
+            _posix.sync_descriptor(descriptor)
+            os.close(descriptor)
+            descriptor = -1
+            try:
+                _posix.commit_noreplace(self._container_fd, stage_name, ".identity")
+            except DestinationExists:
+                self._verify_identity()
+                _posix.remove_file_at(self._container_fd, stage_name, stage_entry)
+                stage_entry = None
+            _posix.sync_descriptor(self._container_fd)
+        except BaseException as error:
+            if stage_entry is not None:
+                try:
+                    _posix.remove_file_at(self._container_fd, stage_name, stage_entry)
+                except Exception as cleanup_error:
+                    error.add_note(f"Servatus could not remove identity stage: {cleanup_error}")
+            raise
+        finally:
+            if descriptor >= 0:
+                os.close(descriptor)
+
+    def _verify_identity(self) -> None:
+        assert self._container_fd >= 0
+        try:
+            descriptor = os.open(
+                ".identity",
+                os.O_RDONLY | os.O_CLOEXEC | os.O_NOFOLLOW | os.O_NONBLOCK,
+                dir_fd=self._container_fd,
+            )
+        except OSError as error:
+            raise WorkConflict(f"workspace identity is unavailable: {self._destination}") from error
+        try:
+            identity_entry = os.fstat(descriptor)
+            if (
+                not stat.S_ISREG(identity_entry.st_mode)
+                or identity_entry.st_dev != os.fstat(self._container_fd).st_dev
+                or identity_entry.st_size != len(self._identity)
+            ):
+                raise WorkConflict(f"workspace identity is invalid: {self._destination}")
+            chunks: list[bytes] = []
+            remaining = len(self._identity) + 1
+            while remaining and (chunk := os.read(descriptor, remaining)):
+                chunks.append(chunk)
+                remaining -= len(chunk)
+            if b"".join(chunks) != self._identity:
+                raise WorkConflict(f"workspace belongs to different work: {self._destination}")
+            _posix.ensure_entry(self._container_fd, ".identity", identity_entry)
+        finally:
+            os.close(descriptor)
+
+    def _close(self) -> None:
+        for attribute in ("_work_fd", "_lock_fd", "_container_fd", "_parent_fd"):
+            descriptor = getattr(self, attribute)
+            if descriptor >= 0:
+                with suppress(OSError):
+                    os.close(descriptor)
+                setattr(self, attribute, -1)
+        self._entered = False
+
+
+def _cleanup_workspace(
+    parent_fd: int,
+    name: str,
+    expected: os.stat_result,
+) -> None:
+    _posix.remove_tree_at(parent_fd, name, expected)

servatus/py.typed

@@ -0,0 +1 @@
+

servatus-0.0.1.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: servatus
+Version: 0.0.1
+Summary: Run resumable work through Slurm and atomically publish validated outputs.
+Project-URL: Repository, https://github.com/edoski/servatus
+Project-URL: Issues, https://github.com/edoski/servatus/issues
+Author: Edoardo Galli
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Servatus
+
+Run resumable work through Slurm and atomically publish validated outputs.
+
+Servatus 0.0.1 is a publication-only alpha. It provides a small Python interface for keeping
+private resumable work and exposing an application-built directory atomically. Slurm campaigns
+arrive in a later release.
+
+```sh
+pip install servatus
+```
+
+## Publication
+
+Use `publish` when failed work is disposable:
+
+```python
+from pathlib import Path
+
+from servatus import Draft, publish
+
+
+def build(draft: Draft) -> None:
+    (draft.path / "result.json").write_text('{"status":"complete"}\n')
+
+
+publication = publish(Path("outputs/run-1"), build)
+```
+
+Use `Workspace` when a worker must retain private checkpoints across restarts:
+
+```python
+from servatus import Draft, Workspace
+
+destination = Path("outputs/model-1")
+with Workspace(destination, identity=b"model request bytes") as workspace:
+    checkpoint = workspace.path / "last.ckpt"
+    # The application creates or resumes its own checkpoint here.
+
+    def assemble(draft: Draft) -> None:
+        draft.link(checkpoint, "last.ckpt")
+        # Perform application validation before returning.
+
+    publication = workspace.publish(assemble)
+```
+
+`Workspace` binds its stable hidden state to the SHA-256 digest of the opaque identity and holds a
+nonblocking writer lock. `Draft.link` only hard-links regular files into a safe relative path. The
+application must not mutate a linked source inode after `Draft.link()` returns and before
+publication completes. It owns file contents, validation, schemas, and completion meaning.
+
+## Guarantees
+
+- A destination is absent or one complete directory; it is never overwritten.
+- Work, hard-link sources, stages, and destination must share a filesystem.
+- Files and directories are synced before a kernel-exclusive commit; the destination parent is
+  synced afterward.
+- Builder failures expose no destination. Resumable work remains available, while disposable
+  stages are removed.
+- Successful workspace publication removes private state. A cleanup failure returns
+  `Publication(cleanup_pending=True)` without misreporting the committed destination as failed.
+- Symlinks, special files, escaping link paths, path substitution, and unsupported exclusive-rename
+  primitives fail closed.
+
+Servatus supports POSIX filesystems on Linux and macOS. Hardware durability still depends on the
+filesystem and mount. It is not a security boundary against another process that can arbitrarily
+modify the same parent directory.
+
+## Non-goals in 0.0.1
+
+Servatus does not interpret checkpoints or ML artifacts, decide when work is valid, model workflow
+graphs, migrate old outputs, copy across filesystems, overwrite destinations, or provide scheduler
+execution. It has no plugins, callbacks beyond the one build seam, runtime dependencies, daemon,
+database, or global run store.
+
+The public API is `Draft`, `Workspace`, `Publication`, `publish`, and the compact errors exported by
+`servatus`. See [the context glossary](docs/CONTEXT.md) and [architecture decisions](docs/adr/README.md)
+for the ownership boundary.

servatus-0.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+servatus/__init__.py,sha256=AGI3N-Gg96BqAPHOtyy2DLabYzz3HcENi36cqCIjVss,537
+servatus/_errors.py,sha256=Q4nndE_WoH9AKcnbRPsOB6NkO7INcCdCg-8XpFCZBmA,817
+servatus/_posix.py,sha256=RnkBU-xSJEPAwvHKlZtxUE81kVNS_wICKA3oSob_I7w,11250
+servatus/_workspace.py,sha256=fEskWfiZOMfXwqCaNsokeRcmu0y4CJReMQ9TArbqAKg,11820
+servatus/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+servatus-0.0.1.dist-info/METADATA,sha256=LTQQC8d47hdds7wbYWuuzM_19VvoZobXxldPBr5aYDg,3890
+servatus-0.0.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+servatus-0.0.1.dist-info/licenses/LICENSE,sha256=wV0fwxnUW3dIricT7A8U12uqgYn9qoXADUbb2P19U7w,1070
+servatus-0.0.1.dist-info/RECORD,,

servatus-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

servatus-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edoardo Galli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.