contextbase-shared-plugins 0.2.3__py3-none-any.whl

shared_plugins/scratch.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import shutil
+from collections.abc import Mapping
+from pathlib import Path
+from uuid import uuid4
+
+from .env import CTXB_SCRATCH_DIR_ENV_VAR, load_shared_python_settings
+
+
+def _validate_safe_segment(value: str, *, label: str) -> str:
+    normalized = value.strip()
+    if not normalized:
+        raise ValueError(f"{label} cannot be blank.")
+    if normalized in {".", ".."}:
+        raise ValueError(f"{label} cannot be '.' or '..'.")
+    if "/" in normalized or "\\" in normalized or "\x00" in normalized:
+        raise ValueError(f"{label} cannot contain path separators or null bytes.")
+    return normalized
+
+
+def _resolve_scratch_root() -> Path:
+    scratch_root = load_shared_python_settings().ctx_scratch_dir
+    if scratch_root is None:
+        raise RuntimeError(
+            f"{CTXB_SCRATCH_DIR_ENV_VAR} is not set; run via ctxb so scratch paths are configured."
+        )
+    return scratch_root
+
+
+def _parse_relative_dir(relative_dir: str) -> Path:
+    normalized = relative_dir.strip()
+    if not normalized:
+        raise ValueError("relative_dir cannot be blank.")
+
+    relative_path = Path(normalized)
+    if relative_path.is_absolute():
+        raise ValueError("relative_dir must be relative, not absolute.")
+
+    safe_parts = [
+        _validate_safe_segment(part, label="relative_dir segment")
+        for part in relative_path.parts
+    ]
+    return Path(*safe_parts)
+
+
+def _resolve_binding_target_paths(
+    *,
+    binding_id: str,
+    relative_dir: str,
+) -> tuple[Path, Path]:
+    scratch_root = _resolve_scratch_root()
+    safe_binding_id = _validate_safe_segment(binding_id, label="binding_id")
+    safe_relative_dir = _parse_relative_dir(relative_dir)
+
+    binding_root = (scratch_root / safe_binding_id).absolute()
+    target_dir = (binding_root / safe_relative_dir).absolute()
+    if not target_dir.is_relative_to(binding_root):
+        raise ValueError("relative_dir escapes the binding scratch root.")
+    return binding_root, target_dir
+
+
+def _remove_path(path: Path) -> None:
+    if not path.exists():
+        return
+    if path.is_dir():
+        shutil.rmtree(path)
+    else:
+        path.unlink()
+
+
+def _build_temp_path(binding_root: Path, *, prefix: str) -> Path:
+    return binding_root / f".{prefix}-{uuid4().hex}"
+
+
+def replace_scratch_dir_files(
+    *,
+    binding_id: str,
+    relative_dir: str,
+    files: Mapping[str, bytes],
+) -> dict[str, str]:
+    binding_root, target_dir = _resolve_binding_target_paths(
+        binding_id=binding_id,
+        relative_dir=relative_dir,
+    )
+    binding_root.mkdir(parents=True, exist_ok=True)
+
+    staging_dir = _build_temp_path(binding_root, prefix="ctx-staging")
+    staging_dir.mkdir(parents=False, exist_ok=False)
+
+    safe_name_by_input_name: dict[str, str] = {}
+    normalized_safe_names: set[str] = set()
+    for file_name, content in files.items():
+        safe_file_name = _validate_safe_segment(file_name, label="file name")
+        if not isinstance(content, bytes):
+            raise TypeError("files values must be bytes.")
+
+        if safe_file_name in normalized_safe_names:
+            raise ValueError(
+                f"files contains duplicate normalized file names: '{safe_file_name}'."
+            )
+        normalized_safe_names.add(safe_file_name)
+        safe_name_by_input_name[file_name] = safe_file_name
+
+        file_path = staging_dir / safe_file_name
+        file_path.write_bytes(content)
+
+    backup_path: Path | None = None
+    try:
+        target_dir.parent.mkdir(parents=True, exist_ok=True)
+        if target_dir.exists():
+            backup_path = _build_temp_path(binding_root, prefix="ctx-backup")
+            target_dir.rename(backup_path)
+        staging_dir.rename(target_dir)
+    except Exception:
+        if backup_path is not None and backup_path.exists() and not target_dir.exists():
+            backup_path.rename(target_dir)
+        raise
+    finally:
+        _remove_path(staging_dir)
+        if backup_path is not None:
+            _remove_path(backup_path)
+
+    return {
+        file_name: str((target_dir / safe_name).absolute())
+        for file_name, safe_name in safe_name_by_input_name.items()
+    }

shared_plugins/sqlalchemy_types.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from sqlalchemy.types import Float, Integer, TypeDecorator
+
+
+def _timedelta_total_microseconds(delta: timedelta) -> int:
+    return ((delta.days * 86_400) + delta.seconds) * 1_000_000 + delta.microseconds
+
+
+def _timedelta_total_milliseconds(delta: timedelta) -> int:
+    total_microseconds = _timedelta_total_microseconds(delta)
+    if total_microseconds >= 0:
+        return total_microseconds // 1_000
+    return -((-total_microseconds) // 1_000)
+
+
+APPLE_CORE_DATA_EPOCH = datetime(2001, 1, 1, tzinfo=timezone.utc)
+
+
+class AppleCoreDataTimestamp(TypeDecorator[datetime | None]):
+    """Store Apple Core Data timestamps as aware UTC datetimes."""
+
+    impl = Float
+    cache_ok = True
+
+    def __init__(self, *, null_sentinels: Iterable[float] = ()) -> None:
+        super().__init__()
+        self.null_sentinels = tuple(
+            sorted({float(sentinel) for sentinel in null_sentinels})
+        )
+
+    def process_bind_param(
+        self,
+        value: object,
+        dialect: Any,
+    ) -> float | None:
+        del dialect
+        if value is None:
+            return None
+        if not isinstance(value, datetime):
+            raise TypeError(
+                "AppleCoreDataTimestamp values must be datetime instances or None."
+            )
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise TypeError("AppleCoreDataTimestamp requires an aware datetime.")
+
+        normalized = value.astimezone(timezone.utc)
+        return (normalized - APPLE_CORE_DATA_EPOCH).total_seconds()
+
+    def process_result_value(
+        self,
+        value: object,
+        dialect: Any,
+    ) -> datetime | None:
+        del dialect
+        if value is None:
+            return None
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise TypeError(
+                "AppleCoreDataTimestamp database values must be numeric or None."
+            )
+
+        numeric_value = float(value)
+        if numeric_value in self.null_sentinels:
+            return None
+
+        return APPLE_CORE_DATA_EPOCH + timedelta(seconds=numeric_value)
+
+
+class AppleMessageTimestamp(TypeDecorator[datetime | None]):
+    """Store iMessage timestamps as aware UTC datetimes.
+
+    iMessage's ``chat.db`` stores timestamps as **nanoseconds** since
+    2001-01-01 UTC starting with iOS 12 / macOS Mojave; pre-iOS 11 databases
+    stored the same columns as **seconds** since the same epoch. Rows from a
+    restored backup can mix both formats in the same column, so each value is
+    classified by magnitude: anything below 10**12 is treated as seconds and
+    everything else as nanoseconds. Sub-microsecond precision is lost on read
+    since ``datetime`` cannot represent it.
+    """
+
+    impl = Integer
+    cache_ok = True
+
+    def __init__(self, *, null_sentinels: Iterable[int] = ()) -> None:
+        super().__init__()
+        self.null_sentinels = tuple(
+            sorted({int(sentinel) for sentinel in null_sentinels})
+        )
+
+    def process_bind_param(
+        self,
+        value: object,
+        dialect: Any,
+    ) -> int | None:
+        del dialect
+        if value is None:
+            return None
+        if not isinstance(value, datetime):
+            raise TypeError(
+                "AppleMessageTimestamp values must be datetime instances or None."
+            )
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise TypeError("AppleMessageTimestamp requires an aware datetime.")
+
+        normalized = value.astimezone(timezone.utc)
+        delta = normalized - APPLE_CORE_DATA_EPOCH
+        return _timedelta_total_microseconds(delta) * 1_000
+
+    def process_result_value(
+        self,
+        value: object,
+        dialect: Any,
+    ) -> datetime | None:
+        del dialect
+        if value is None:
+            return None
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise TypeError(
+                "AppleMessageTimestamp database values must be int or None."
+            )
+
+        if value in self.null_sentinels:
+            return None
+
+        if value >= 10**12:
+            microseconds = value // 1_000
+            return APPLE_CORE_DATA_EPOCH + timedelta(microseconds=microseconds)
+
+        return APPLE_CORE_DATA_EPOCH + timedelta(seconds=value)
+
+
+CHROMIUM_EPOCH = datetime(1601, 1, 1, tzinfo=timezone.utc)
+
+
+class ChromiumTimestamp(TypeDecorator[datetime | None]):
+    """Store Chromium timestamps as aware UTC datetimes.
+
+    Chromium stores timestamps as microseconds since 1601-01-01 00:00:00 UTC.
+    """
+
+    impl = Integer
+    cache_ok = True
+
+    def process_bind_param(
+        self,
+        value: object,
+        dialect: Any,
+    ) -> int | None:
+        del dialect
+        if value is None:
+            return None
+        if not isinstance(value, datetime):
+            raise TypeError(
+                "ChromiumTimestamp values must be datetime instances or None."
+            )
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise TypeError("ChromiumTimestamp requires an aware datetime.")
+
+        normalized = value.astimezone(timezone.utc)
+        delta = normalized - CHROMIUM_EPOCH
+        return _timedelta_total_microseconds(delta)
+
+    def process_result_value(
+        self,
+        value: object,
+        dialect: Any,
+    ) -> datetime | None:
+        del dialect
+        if value is None:
+            return None
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise TypeError(
+                "ChromiumTimestamp database values must be numeric or None."
+            )
+
+        return CHROMIUM_EPOCH + timedelta(microseconds=int(value))
+
+
+UNIX_EPOCH = datetime(1970, 1, 1, tzinfo=timezone.utc)
+
+
+class UnixMillisTimestamp(TypeDecorator[datetime | None]):
+    """Store Unix-millisecond timestamps as aware UTC datetimes."""
+
+    impl = Integer
+    cache_ok = True
+
+    def process_bind_param(
+        self,
+        value: object,
+        dialect: Any,
+    ) -> int | None:
+        del dialect
+        if value is None:
+            return None
+        if not isinstance(value, datetime):
+            raise TypeError(
+                "UnixMillisTimestamp values must be datetime instances or None."
+            )
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise TypeError("UnixMillisTimestamp requires an aware datetime.")
+
+        normalized = value.astimezone(timezone.utc)
+        delta = normalized - UNIX_EPOCH
+        return _timedelta_total_milliseconds(delta)
+
+    def process_result_value(
+        self,
+        value: object,
+        dialect: Any,
+    ) -> datetime | None:
+        del dialect
+        if value is None:
+            return None
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise TypeError(
+                "UnixMillisTimestamp database values must be numeric or None."
+            )
+
+        return UNIX_EPOCH + timedelta(milliseconds=int(value))

shared_plugins/sqlite.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import logging
+import shutil
+import sqlite3
+import tempfile
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+from urllib.parse import urlencode
+
+LOGGER = logging.getLogger(__name__)
+
+BACKUP_TIMEOUT_SECONDS = 5.0
+BACKUP_PAGES_PER_STEP = 100
+SQLITE_COPY_SIBLING_SUFFIXES = ("-journal", "-wal", "-shm")
+
+
+class _BackupTimeout(Exception):
+    """Internal sentinel raised from the backup progress callback."""
+
+
+@contextmanager
+def sqlite_snapshot(
+    db_path: Path,
+    *,
+    backup_timeout: float = BACKUP_TIMEOUT_SECONDS,
+) -> Iterator[Path]:
+    """Create a consistent snapshot of a potentially-locked SQLite database.
+
+    Yields a path to a temporary copy that the caller can open with any
+    library (raw sqlite3, SQLAlchemy, etc.). The temporary directory and
+    all files are deleted when the context manager exits.
+
+    Strategy:
+
+    1. Try the SQLite Online Backup API with cooperative timeout. A
+       `progress` callback fires after every backup_step iteration —
+       including SQLITE_BUSY / SQLITE_LOCKED — and aborts the backup
+       by raising when the wall-clock deadline is exceeded. The source
+       connection is opened with `timeout=0` so SQLite's internal busy
+       retry doesn't loop in C; control returns to Python between every
+       step, which is where we check the deadline.
+
+    2. If the backup deadline is exceeded, fall back to copying the
+       database file and any rollback-journal or WAL siblings. Best-
+       effort: not transactionally guaranteed, but works across SQLite
+       journal modes.
+
+    Non-timeout errors (missing file, corrupt DB, etc.) propagate to
+    the caller — they are not part of the "should we fall back?"
+    decision.
+    """
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        snapshot_dir = Path(tmp_dir)
+        snapshot_path = snapshot_dir / db_path.name
+        if _try_backup(db_path, snapshot_path, backup_timeout):
+            LOGGER.debug("sqlite_snapshot.backup_ok path=%s", db_path)
+        else:
+            LOGGER.info(
+                "sqlite_snapshot.backup_timeout path=%s timeout=%.1fs, falling back to file copy",
+                db_path,
+                backup_timeout,
+            )
+            _copy_with_siblings(db_path, snapshot_dir)
+
+        yield snapshot_path
+
+
+def _try_backup(db_path: Path, dest_path: Path, timeout: float) -> bool:
+    """Attempt a backup-API snapshot. Returns True on success, False on timeout."""
+    deadline = time.monotonic() + timeout
+
+    def abort_if_past_deadline(rc: int, remaining: int, total: int) -> None:
+        if time.monotonic() > deadline:
+            raise _BackupTimeout()
+
+    # timeout=0 disables SQLite's internal busy retry so the progress
+    # callback fires on every BUSY/LOCKED step (otherwise SQLite's C
+    # layer would loop on BUSY for up to busy_timeout before returning
+    # to Python, and we'd lose our cooperative cancellation point).
+    source = sqlite3.connect(_sqlite_readonly_uri(db_path), uri=True, timeout=0)
+    try:
+        dest = sqlite3.connect(dest_path)
+        try:
+            source.backup(
+                dest,
+                pages=BACKUP_PAGES_PER_STEP,
+                progress=abort_if_past_deadline,
+            )
+            return True
+        except _BackupTimeout:
+            _cleanup_partial_backup(dest_path)
+            return False
+        finally:
+            dest.close()
+    finally:
+        source.close()
+
+
+def _copy_with_siblings(db_path: Path, dest_dir: Path) -> None:
+    """Copy a database file and any rollback-journal or WAL siblings."""
+    for artifact in _iter_sqlite_artifacts(db_path):
+        if artifact.is_file():
+            shutil.copy2(artifact, dest_dir / artifact.name)
+
+
+def _cleanup_partial_backup(dest_path: Path) -> None:
+    for artifact in _iter_sqlite_artifacts(dest_path):
+        if artifact.exists():
+            artifact.unlink()
+
+
+def _iter_sqlite_artifacts(db_path: Path) -> Iterator[Path]:
+    yield db_path
+    for suffix in SQLITE_COPY_SIBLING_SUFFIXES:
+        yield db_path.parent / f"{db_path.name}{suffix}"
+
+
+def _sqlite_readonly_uri(db_path: Path) -> str:
+    base_uri = db_path.resolve(strict=False).as_uri()
+    return f"{base_uri}?{urlencode({'mode': 'ro'})}"

shared_plugins/values.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from typing import Any
+
+
+def as_mapping(value: object) -> Mapping[str, Any] | None:
+    if not isinstance(value, Mapping):
+        return None
+    return value
+
+
+def as_string(value: object) -> str | None:
+    if isinstance(value, str):
+        return value
+    return None
+
+
+def non_empty_string(value: object) -> str | None:
+    text = as_string(value)
+    if text is None:
+        return None
+    stripped = text.strip()
+    return stripped or None
+
+
+def coerce_non_empty_string_mapping(value: object) -> dict[str, str]:
+    if value is None:
+        return {}
+    if not isinstance(value, Mapping):
+        raise ValueError(
+            "Expected a mapping of non-empty string keys to non-empty string values."
+        )
+
+    mapping: dict[str, str] = {}
+    for key, raw_value in value.items():
+        if not isinstance(key, str) or key == "" or key != key.strip():
+            raise ValueError(
+                "Expected a mapping of non-empty string keys to non-empty string values."
+            )
+        if (
+            not isinstance(raw_value, str)
+            or raw_value == ""
+            or raw_value != raw_value.strip()
+        ):
+            raise ValueError(
+                "Expected a mapping of non-empty string keys to non-empty string values."
+            )
+        mapping[key] = raw_value
+    return mapping
+
+
+def load_json_value(value: object) -> Any:
+    if isinstance(value, (dict, list)):
+        return value
+    if isinstance(value, str):
+        return json.loads(value)
+    return None
+
+
+def require_non_empty_text(
+    value: object,
+    *,
+    label: str,
+    context: str = "payload",
+) -> str:
+    if isinstance(value, str):
+        text = value.strip() or None
+    elif value is None:
+        text = None
+    else:
+        text = str(value).strip() or None
+    if text is None:
+        raise RuntimeError(f"{context} is missing required field '{label}'.")
+    return text
+
+
+def require_non_negative_int(
+    value: object,
+    *,
+    message: str = "must be a non-negative integer",
+) -> int:
+    if value is None or isinstance(value, bool):
+        raise ValueError(message)
+    if isinstance(value, int):
+        if value >= 0:
+            return value
+        raise ValueError(message)
+    if isinstance(value, str):
+        stripped = value.strip()
+        if stripped == "":
+            raise ValueError(message)
+        try:
+            parsed = int(stripped)
+        except ValueError as exc:
+            raise ValueError(message) from exc
+        if parsed >= 0:
+            return parsed
+    raise ValueError(message)
+
+
+def parse_utc_datetime_from_str(value: str) -> datetime | None:
+    if not isinstance(value, str):
+        raise TypeError(f"Expected str, got {type(value).__name__}")
+
+    text = value.strip()
+    if not text:
+        return None
+
+    normalized = f"{text[:-1]}+00:00" if text.endswith("Z") else text
+    parsed = datetime.fromisoformat(normalized)
+
+    if parsed.tzinfo is None or parsed.utcoffset() is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)