l3io-wordpress-database 0.3.5__py3-none-any.whl

l3io/wp/database/__init__.py

@@ -0,0 +1,192 @@
+"""WordPress database operations, each checked before it runs.
+
+``l3io`` and ``l3io.wp`` are a PEP 420 namespace shared with
+``l3io-wordpress-config`` and ``l3io-wordpress-backup``; this is the only
+``__init__.py`` above this directory (AD-27).
+
+The identifier helpers are public because AD-28 requires grant-target escaping
+to go through one shared function: dependents import ``quote_grant_database``
+from here rather than reimplementing it.
+"""
+
+from __future__ import annotations
+
+from ._client import ClientTool
+from ._version import __version__
+from .auth import ALLOWED_AUTH_PLUGINS, REFUSED_AUTH_PLUGINS
+from .connection import DEFAULT_PORT, Connection
+from .credentials import (
+    AwsSecretsManager,
+    CredentialChain,
+    CredentialSource,
+    Environment,
+    Explicit,
+    ResolvedCredentials,
+)
+from .encryption import (
+    check_passphrase,
+    check_recipients,
+    decrypt,
+    encrypt,
+    generate_identity,
+)
+from .errors import (
+    AccessDeniedError,
+    AuthenticationFailedError,
+    AuthPluginRefusedError,
+    ConfigUnreadableError,
+    ConfigurationError,
+    CorruptDumpError,
+    CredentialsAbsentError,
+    CredentialsUnobtainableError,
+    DatabaseError,
+    DatabaseUnreachableError,
+    DecryptionError,
+    InvalidArgumentsError,
+    InvalidDatabaseNameError,
+    InvalidIdentifierError,
+    MissingConfigValueError,
+    MissingDependencyError,
+    ProvisioningError,
+    RefusedError,
+    RegionNotKnownError,
+    TlsHandshakeError,
+    TlsVerificationError,
+    TransferError,
+)
+from .facade import Database
+from .identifiers import (
+    quote_grant_database,
+    quote_identifier,
+    validate_database_name,
+    validate_user_name,
+)
+from .inspection import Survey, inspect, schema_version, survey
+from .provision import (
+    EnsureResult,
+    OperationResult,
+    check_drop_database,
+    check_drop_user,
+    check_ensure,
+    check_revoke,
+    check_rotate_password,
+    drop_database,
+    drop_user,
+    ensure,
+    revoke,
+    rotate_password,
+)
+from .server import ServerFamily, ServerInfo
+from .state import ConnectionState
+from .tls import (
+    DEFAULT_LOCAL_HOSTS,
+    TlsMode,
+    TlsSettings,
+    tls_required_unless_local,
+)
+from .transfer import (
+    DropTablesResult,
+    DumpStream,
+    TransferResult,
+    check_drop_tables,
+    check_dump,
+    check_load,
+    drop_tables,
+    dump,
+    iter_dump,
+    load,
+    validate_table_prefix,
+)
+from .verdict import Code, Finding, Severity, Verdict
+from .versions import SUPPORTED_FROM, SchemaVersion, release_for
+from .wpconfig import DEFAULT_TABLE_PREFIX, WpConfigFile
+
+__all__ = [
+    "ALLOWED_AUTH_PLUGINS",
+    "AccessDeniedError",
+    "AuthPluginRefusedError",
+    "AuthenticationFailedError",
+    "AwsSecretsManager",
+    "ClientTool",
+    "Code",
+    "ConfigUnreadableError",
+    "ConfigurationError",
+    "Connection",
+    "ConnectionState",
+    "CorruptDumpError",
+    "CredentialChain",
+    "CredentialSource",
+    "CredentialsAbsentError",
+    "CredentialsUnobtainableError",
+    "DEFAULT_LOCAL_HOSTS",
+    "DEFAULT_PORT",
+    "DEFAULT_TABLE_PREFIX",
+    "Database",
+    "DatabaseError",
+    "DatabaseUnreachableError",
+    "DecryptionError",
+    "DropTablesResult",
+    "DumpStream",
+    "EnsureResult",
+    "Environment",
+    "Explicit",
+    "Finding",
+    "InvalidArgumentsError",
+    "InvalidDatabaseNameError",
+    "InvalidIdentifierError",
+    "MissingConfigValueError",
+    "MissingDependencyError",
+    "OperationResult",
+    "ProvisioningError",
+    "REFUSED_AUTH_PLUGINS",
+    "RefusedError",
+    "RegionNotKnownError",
+    "ResolvedCredentials",
+    "SUPPORTED_FROM",
+    "SchemaVersion",
+    "ServerFamily",
+    "ServerInfo",
+    "Severity",
+    "Survey",
+    "TlsHandshakeError",
+    "TlsMode",
+    "TlsSettings",
+    "TlsVerificationError",
+    "TransferError",
+    "TransferResult",
+    "Verdict",
+    "WpConfigFile",
+    "__version__",
+    "check_drop_database",
+    "check_drop_tables",
+    "check_drop_user",
+    "check_dump",
+    "check_ensure",
+    "check_load",
+    "check_passphrase",
+    "check_recipients",
+    "check_revoke",
+    "check_rotate_password",
+    "decrypt",
+    "drop_database",
+    "drop_tables",
+    "drop_user",
+    "dump",
+    "encrypt",
+    "ensure",
+    "generate_identity",
+    "inspect",
+    "iter_dump",
+    "load",
+    "quote_grant_database",
+    "quote_identifier",
+    "release_for",
+    "revoke",
+    "rotate_password",
+    "schema_version",
+    "survey",
+    "tls_required_unless_local",
+    "validate_database_name",
+    "validate_table_prefix",
+    "validate_user_name",
+]

l3io/wp/database/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m l3io.wp.database``."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

l3io/wp/database/_client.py

@@ -0,0 +1,318 @@
+"""The MySQL and MariaDB client programs: finding them, and running them without
+exposing a password. Internal.
+
+A password never appears in an argument vector, a child's environment, or a file
+on disk (spec §2.4). The client reads its options from an anonymous pipe named
+``--defaults-file=/dev/fd/N`` and placed first, which also stops it reading
+``~/.my.cnf``. MySQL clients still read ``~/.mylogin.cnf`` after that, so login
+paths are suppressed: ``MYSQL_TEST_LOGIN_FILE`` points at nothing for every
+client, and MySQL 8.4+ also gets ``--no-login-paths`` (probe V2; MariaDB has no
+login-path file). The child environment holds nothing else that could redirect
+or authenticate it.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+
+from .connection import Connection
+from .credentials import ResolvedCredentials
+from .errors import InvalidArgumentsError
+from .server import ServerFamily
+
+PURPOSE_DUMP = "dump"
+PURPOSE_LOAD = "load"
+
+_CANDIDATES: dict[str, dict[ServerFamily, tuple[str, ...]]] = {
+    PURPOSE_DUMP: {
+        ServerFamily.MARIADB: ("mariadb-dump", "mysqldump"),
+        ServerFamily.MYSQL: ("mysqldump",),
+    },
+    PURPOSE_LOAD: {
+        ServerFamily.MARIADB: ("mariadb", "mysql"),
+        ServerFamily.MYSQL: ("mysql",),
+    },
+}
+
+_MARIADB_VERSION = re.compile(r"(?:Distrib|from) (\d+)\.(\d+)\.(\d+)-MariaDB")
+_MYSQL_VERSION = re.compile(r"\bVer (\d+)\.(\d+)\.(\d+)")
+
+#: First MariaDB client release, per series, that reads the sandbox line MariaDB
+#: dumps begin with (MDEV-33727). MySQL clients read it as a comment (probe V1).
+#: A series absent here and older than the newest listed is treated as unable.
+_SANDBOX_SINCE: dict[tuple[int, int], int] = {
+    (10, 5): 25,
+    (10, 6): 18,
+    (10, 11): 8,
+    (11, 0): 6,
+    (11, 1): 5,
+    (11, 2): 4,
+    (11, 4): 2,
+}
+
+_NO_LOGIN_FILE = "/nonexistent/l3io-wordpress-database/no-login-file"
+
+_MAX_VALUE_BYTES = 1024
+
+#: Options a caller may add. Anything touching credentials, option files, the
+#: host or an output file is refused by omission. ``--enable-cleartext-plugin``
+#: is deliberately absent: the mysql client must keep cleartext auth off.
+DUMP_OPTIONS = frozenset(
+    {
+        "--routines",
+        "--events",
+        "--skip-triggers",
+        "--ignore-table",
+        "--no-data",
+        "--skip-extended-insert",
+        "--where",
+        "--max-allowed-packet",
+    }
+)
+LOAD_OPTIONS = frozenset({"--binary-mode", "--max-allowed-packet"})
+
+
+@dataclass(frozen=True, slots=True)
+class ClientTool:
+    """One client program, and what it is."""
+
+    name: str
+    path: str
+    family: ServerFamily
+    version: tuple[int, int, int]
+    version_text: str
+
+    @property
+    def label(self) -> str:
+        return f"{self.name} {self.version_text}"
+
+    @property
+    def understands_sandbox_line(self) -> bool:
+        if self.family is ServerFamily.MYSQL:
+            return True
+        series = self.version[:2]
+        if series > max(_SANDBOX_SINCE):
+            return True
+        since = _SANDBOX_SINCE.get(series)
+        return since is not None and self.version[2] >= since
+
+
+def parse_client_version(name: str, path: str, text: str) -> ClientTool:
+    """Interpret a client program's ``--version`` output."""
+    match = _MARIADB_VERSION.search(text)
+    family = ServerFamily.MARIADB
+    if match is None:
+        match = _MYSQL_VERSION.search(text)
+        family = ServerFamily.MYSQL
+    if match is None:
+        msg = f"unrecognised client version {text.strip()!r}"
+        raise ValueError(msg)
+    major, minor, patch = (int(g) for g in match.groups())
+    return ClientTool(name, path, family, (major, minor, patch), text.strip())
+
+
+def sanitized_path(raw: str | None = None) -> str:
+    """``PATH`` with empty and relative entries dropped (BL-E004-055).
+
+    A relative PATH entry would let a child resolve tools against the caller's
+    cwd. Only absolute directories remain.
+    """
+    source = os.environ.get("PATH", os.defpath) if raw is None else raw
+    return os.pathsep.join(
+        entry for entry in source.split(os.pathsep) if entry and Path(entry).is_absolute()
+    )
+
+
+def which_absolute(name: str, *, path: str | None = None) -> str | None:
+    """``shutil.which`` over a sanitized PATH; refuse a non-absolute result."""
+    search = sanitized_path() if path is None else sanitized_path(path)
+    if not search:
+        return None
+    found = shutil.which(name, path=search)
+    if found is None or not Path(found).is_absolute():
+        return None
+    return found
+
+
+def child_env() -> dict[str, str]:
+    """The entire environment a client program gets.
+
+    No ``HOME``, ``MYSQL_PWD``, ``MYSQL_HOST`` or ``MYSQL_TCP_PORT``: nothing
+    inherited can authenticate or redirect it. Credentials arrive only through
+    the option-file pipe. ``PATH`` is sanitized; ``LC_ALL`` is ``C``.
+    """
+    return {
+        "PATH": sanitized_path(),
+        "LC_ALL": "C",
+        "MYSQL_TEST_LOGIN_FILE": _NO_LOGIN_FILE,
+    }
+
+
+def age_child_env(*, passphrase_fd: int) -> dict[str, str]:
+    """Minimal environment for ``age`` and plugins it may exec (BL-E004-055).
+
+    Absolute ``PATH`` only, ``LC_ALL=C``, an absolute ``HOME`` when the parent
+    has one (else a non-existent absolute path), and ``AGE_PASSPHRASE_FD``.
+    No other parent variables (cloud keys, ``L3IO_WP_BACKUP_*``, …).
+    """
+    home = os.environ.get("HOME", "")
+    return {
+        "PATH": sanitized_path(),
+        "HOME": home if home and Path(home).is_absolute() else "/nonexistent",
+        "LC_ALL": "C",
+        "AGE_PASSPHRASE_FD": str(passphrase_fd),
+    }
+
+
+def candidates(purpose: str, family: ServerFamily) -> tuple[str, ...]:
+    """Program names to try for this server: its own family's first."""
+    other = ServerFamily.MYSQL if family is ServerFamily.MARIADB else ServerFamily.MARIADB
+    names = (*_CANDIDATES[purpose][family], *_CANDIDATES[purpose][other])
+    return tuple(dict.fromkeys(names))
+
+
+def find_tool(purpose: str, family: ServerFamily) -> ClientTool | None:
+    """The best client program on ``PATH`` for this server, or ``None``."""
+    for name in candidates(purpose, family):
+        path = which_absolute(name)
+        if path is None:
+            continue
+        try:
+            done = subprocess.run(  # noqa: S603 - an absolute path found on PATH, fixed argument
+                [path, "--version"],
+                capture_output=True,
+                text=True,
+                timeout=15,
+                env=child_env(),
+                check=False,
+            )
+            return parse_client_version(name, path, done.stdout or done.stderr)
+        except (OSError, subprocess.SubprocessError, ValueError):
+            continue
+    return None
+
+
+def _quote(field: str, value: str) -> str:
+    """An option-file value: quoted, with backslash, quote and newline escaped (V5).
+
+    MariaDB reads an option line longer than its fixed buffer (about 4 KiB) as
+    two lines, quoted or not, so an overlong value would smuggle in an option of
+    the caller's choosing. Values are capped well below that. No message here
+    may carry the value, and no refusal may chain the encoder's exception, whose
+    ``object`` is the value itself.
+    """
+    if "\x00" in value:
+        msg = "a connection value cannot contain a NUL character"
+        raise InvalidArgumentsError(msg)
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+    try:
+        size = len(escaped.encode())
+    except UnicodeEncodeError:
+        size = None
+    if size is None:
+        msg = f"the {field} is not valid UTF-8 text"
+        raise InvalidArgumentsError(msg)
+    if size > _MAX_VALUE_BYTES:
+        msg = f"the {field} is longer than {_MAX_VALUE_BYTES} bytes once escaped"
+        raise InvalidArgumentsError(msg)
+    return f'"{escaped}"'
+
+
+def option_file_text(
+    credentials: ResolvedCredentials, connection: Connection, family: ServerFamily
+) -> str:
+    """The ``[client]`` options a program reads from the pipe.
+
+    ``family`` selects TLS option names the client accepts (MySQL ``ssl-mode``
+    vs MariaDB ``ssl`` / ``ssl-verify-server-cert``).
+    """
+    from .tls import option_file_lines
+
+    lines = [
+        "[client]",
+        f"user={_quote('user', credentials.username)}",
+        f"password={_quote('password', credentials.password)}",
+        f"host={_quote('host', connection.host)}",
+        f"port={connection.port}",
+        "protocol=TCP",
+        *option_file_lines(connection.tls, family),
+    ]
+    return "\n".join(lines) + "\n"
+
+
+@contextmanager
+def option_pipe(
+    credentials: ResolvedCredentials, connection: Connection, family: ServerFamily
+) -> Iterator[int]:
+    """A pipe holding the option file; yields its read end, closed on exit.
+
+    Pass the fd with ``pass_fds`` and name it ``/dev/fd/N``. Nothing touches disk.
+    """
+    data = option_file_text(credentials, connection, family).encode()
+    read_fd, write_fd = os.pipe()
+    try:
+        while data:
+            data = data[os.write(write_fd, data) :]
+    finally:
+        os.close(write_fd)
+    try:
+        yield read_fd
+    finally:
+        os.close(read_fd)
+
+
+def disallowed_options(options: Sequence[str], allowed: frozenset[str]) -> list[str]:
+    """Caller options whose name is not on the allow-list."""
+    return [o for o in options if o.split("=", 1)[0] not in allowed]
+
+
+def _login_path_args(tool: ClientTool) -> list[str]:
+    if tool.family is ServerFamily.MYSQL and tool.version >= (8, 4, 0):
+        return ["--no-login-paths"]
+    return []
+
+
+def argv(tool: ClientTool, fd: int, args: Sequence[str]) -> list[str]:
+    """The full argument vector: the option file first, then login-path suppression."""
+    return [tool.path, f"--defaults-file=/dev/fd/{fd}", *_login_path_args(tool), *args]
+
+
+def dump_args(
+    tool: ClientTool,
+    database: str,
+    options: Sequence[str],
+    *,
+    server_family: ServerFamily | None = None,
+) -> list[str]:
+    """Consistent, streaming, binary-safe, without CREATE DATABASE/USE (V7).
+
+    ``server_family`` is the server being dumped (not the client). MySQL
+    mysqldump 8.0+ queries ``information_schema.COLUMN_STATISTICS`` by default;
+    MariaDB has no such table, so a MySQL-client dump of a MariaDB server fails
+    with error 1109 unless ``--column-statistics=0`` is set. Ubuntu's
+    ``mysql-client`` package is often the only dump tool on PATH for MariaDB
+    hosts (``candidates`` falls back to ``mysqldump``).
+    """
+    args = [
+        "--single-transaction",
+        "--quick",
+        "--hex-blob",
+        "--default-character-set=utf8mb4",
+        "--no-tablespaces",
+    ]
+    if tool.family is ServerFamily.MYSQL:
+        args.append("--set-gtid-purged=OFF")
+        if server_family is ServerFamily.MARIADB and tool.version >= (8, 0, 0):
+            args.append("--column-statistics=0")
+    return [*args, *options, database]
+
+
+def load_args(database: str, options: Sequence[str]) -> list[str]:
+    return ["--default-character-set=utf8mb4", f"--database={database}", *options]

l3io/wp/database/_observe.py

@@ -0,0 +1,157 @@
+"""One span, one timed completion event, per public operation. Internal.
+
+The package never configures logging. A caller that binds a Run ID with
+``structlog.contextvars`` sees it here because the caller's processor chain
+merges it, not because this module does anything.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+import structlog
+from opentelemetry import trace
+from opentelemetry.trace import Status, StatusCode
+
+from .connection import Connection
+from .errors import RefusedError
+from .verdict import Verdict
+
+_log = structlog.get_logger("l3io.wp.database")
+_tracer = trace.get_tracer("l3io.wp.database")
+
+
+def _mark_error(span: trace.Span, error: BaseException) -> None:
+    """Record failure on a span without message or stack (BL-E006-010).
+
+    MySQL and package errors can carry usernames, hosts or SQL. Only the
+    exception type is an attribute; status is ERROR with no description.
+    """
+    span.set_attribute("error.type", type(error).__name__)
+    span.set_status(Status(StatusCode.ERROR))
+
+
+@contextmanager
+def operation(name: str, connection: Connection) -> Iterator[dict[str, object]]:
+    """Wrap one public operation in a span and a completion event."""
+    fields: dict[str, object] = {}
+    started = time.monotonic()
+    with _tracer.start_as_current_span(
+        f"l3io.wp.database.{name}",
+        record_exception=False,
+        set_status_on_exception=False,
+    ) as span:
+        span.set_attribute("db.name", connection.database)
+        span.set_attribute("server.address", connection.host)
+        span.set_attribute("server.port", connection.port)
+        try:
+            yield fields
+        except RefusedError as exc:
+            span.set_attribute("l3io.verdict.codes", [str(f.code) for f in exc.verdict.blockers])
+            _mark_error(span, exc)
+            fields[VERDICT_KEY] = exc.verdict
+            _complete(name, connection, "refused", started, fields)
+            raise
+        except BaseException as exc:
+            _mark_error(span, exc)
+            _complete(name, connection, "failed", started, fields)
+            raise
+        _complete(name, connection, "succeeded", started, fields)
+
+
+class Running:
+    """A public operation that outlives the call that began it, as a dump's stream does.
+
+    Its span is current only inside :meth:`current` and while :meth:`end` logs,
+    never across calls, so ending it from any thread or a finalizer leaves every
+    context as it was. Only the first :meth:`end` counts. Span, attributes,
+    completion event and outcomes are those of :func:`operation`.
+    """
+
+    def __init__(self, name: str, connection: Connection) -> None:
+        self.fields: dict[str, object] = {}
+        self._name = name
+        self._connection = connection
+        self._started = time.monotonic()
+        self._lock = threading.Lock()
+        self._ended = False
+        self._span = _tracer.start_span(f"l3io.wp.database.{name}")
+        self._span.set_attribute("db.name", connection.database)
+        self._span.set_attribute("server.address", connection.host)
+        self._span.set_attribute("server.port", connection.port)
+
+    @contextmanager
+    def current(self) -> Iterator[dict[str, object]]:
+        """Make the span current for a block on the calling thread."""
+        with trace.use_span(
+            self._span, end_on_exit=False, record_exception=False, set_status_on_exception=False
+        ):
+            yield self.fields
+
+    def end(self, error: BaseException | None) -> None:
+        """Complete the operation: succeeded, or refused or failed by ``error``."""
+        with self._lock:
+            if self._ended:
+                return
+            self._ended = True
+        span = self._span
+        if isinstance(error, RefusedError):
+            span.set_attribute("l3io.verdict.codes", [str(f.code) for f in error.verdict.blockers])
+            self.fields[VERDICT_KEY] = error.verdict
+        if isinstance(error, Exception):
+            _mark_error(span, error)
+        outcome = (
+            "succeeded"
+            if error is None
+            else "refused"
+            if isinstance(error, RefusedError)
+            else "failed"
+        )
+        try:
+            # Current only for the event itself, so a caller's log processor sees this span.
+            with trace.use_span(
+                span, end_on_exit=False, record_exception=False, set_status_on_exception=False
+            ):
+                _complete(self._name, self._connection, outcome, self._started, self.fields)
+        finally:
+            span.end()
+
+
+#: An operation puts its Verdict in the yielded dict under this key, so the
+#: warnings it found are logged once, at WARNING level, however it ends (§6).
+VERDICT_KEY = "_verdict"
+
+#: Parameter names of structlog's call chain (BoundLogger method and _proxy_to_logger).
+#: A caller field with one of these names would collide when passed as a keyword.
+_STRUCTLOG_PARAMETERS = frozenset({"self", "method_name"})
+
+
+def _complete(
+    name: str, connection: Connection, outcome: str, started: float, fields: dict[str, object]
+) -> None:
+    # One dict, reserved keys written last: a caller field with a colliding name
+    # must never raise here, because this runs inside the exception handlers.
+    # The event name is structlog's first positional parameter, so it travels as a
+    # keyword too; otherwise a caller field named "event" collides with it.
+    verdict = fields.pop(VERDICT_KEY, None)
+    if isinstance(verdict, Verdict):
+        for finding in verdict.warnings:
+            _log.warning(
+                event=finding.message,
+                code=str(finding.code),
+                operation=name,
+                database=connection.database,
+            )
+    caller_fields = {k: v for k, v in fields.items() if k not in _STRUCTLOG_PARAMETERS}
+    event: dict[str, object] = {
+        **caller_fields,
+        "event": "operation complete",
+        "operation": name,
+        "outcome": outcome,
+        "duration_ms": round((time.monotonic() - started) * 1000, 1),
+        "database": connection.database,
+    }
+    _log.info(**event)