dploydb 0.1.0__py3-none-any.whl

dploydb/deployment_dependencies.py

@@ -0,0 +1,366 @@
+"""Narrow injectable boundaries and configured adapters for deployment."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from dploydb.candidate import (
+    CandidateStageObserver,
+    CandidateValidationResult,
+    HealthChecker,
+    run_candidate_stage,
+)
+from dploydb.config import LoadedConfiguration, ProductionTopology
+from dploydb.cutover import (
+    create_final_backup,
+    migrate_production_database,
+    restore_final_backup,
+)
+from dploydb.health import ApplicationHealthChecker, CandidateHealthResult
+from dploydb.locking import DeploymentLock
+from dploydb.models import (
+    BackupArtifact,
+    MigrationCommandEvidence,
+    ProductionMigrationResult,
+    RemoteBackupArtifact,
+    VerifiedDatabaseRestoreResult,
+)
+from dploydb.releases import ReleaseHistorySnapshot
+from dploydb.retention import RetentionResult, apply_retention
+from dploydb.runners.base import (
+    ApplicationRunner,
+    ProductionApplicationRunner,
+    ProductionStop,
+)
+from dploydb.runners.docker_compose_production import DockerComposeProductionRunner
+from dploydb.state import StateStore
+from dploydb.storage.base import RemoteBackupStorage
+from dploydb.storage.local import LocalBackupStorage
+from dploydb.storage.s3 import configured_s3_storage
+from dploydb.subprocesses import SubprocessRunner
+from dploydb.traffic import CommandTrafficController, TrafficController
+
+
+class PreCutoverStage(Protocol):
+    """Caller-owned rehearsal and candidate boundary."""
+
+    def run(
+        self,
+        loaded: LoadedConfiguration,
+        *,
+        version: str,
+        config_path: Path,
+        operation_id: str,
+        store: StateStore,
+        lock: DeploymentLock,
+        cancellation_event: threading.Event | None,
+        stage_observer: CandidateStageObserver,
+    ) -> CandidateValidationResult: ...
+
+
+class ProductionHealthBoundary(Protocol):
+    """Final and rollback application health boundary."""
+
+    def check_application(
+        self,
+        *,
+        version: str,
+        database_path: Path,
+        cancellation_event: threading.Event | None = None,
+    ) -> CandidateHealthResult: ...
+
+
+class CutoverDatabase(Protocol):
+    """Database transaction boundary owned by the deployment operation."""
+
+    def create_final(
+        self,
+        *,
+        operation_id: str,
+        stopped: ProductionStop,
+    ) -> BackupArtifact: ...
+
+    def migrate(
+        self,
+        *,
+        operation_id: str,
+        stopped: ProductionStop,
+        final_backup: BackupArtifact,
+        traffic_activated: bool,
+        evidence_sink: Callable[[MigrationCommandEvidence], None],
+        cancellation_event: threading.Event | None,
+        log_path: Path,
+    ) -> ProductionMigrationResult: ...
+
+    def restore(
+        self,
+        *,
+        operation_id: str,
+        stopped: ProductionStop,
+        final_backup: BackupArtifact,
+        traffic_activated: bool,
+    ) -> VerifiedDatabaseRestoreResult: ...
+
+
+class FinalBackupReplicator(Protocol):
+    """Required off-server commit boundary before production migration."""
+
+    def replicate(
+        self,
+        artifact: BackupArtifact,
+        *,
+        release_id: str,
+    ) -> RemoteBackupArtifact: ...
+
+
+class PostActivationRetention(Protocol):
+    """Cleanup boundary invoked only after active pointers are durable."""
+
+    def apply(self, history: ReleaseHistorySnapshot) -> RetentionResult: ...
+
+
+@dataclass(frozen=True, slots=True)
+class DeploymentDependencies:
+    """Injectable operational boundaries used by the coordinator."""
+
+    pre_cutover: PreCutoverStage
+    production: ProductionApplicationRunner
+    traffic: TrafficController
+    database: CutoverDatabase
+    health: ProductionHealthBoundary
+    remote_backup: FinalBackupReplicator | None = None
+    retention: PostActivationRetention | None = None
+
+
+class ConfiguredPreCutover:
+    def __init__(
+        self,
+        *,
+        command_environment: Mapping[str, str],
+        command_runner: SubprocessRunner | None,
+        application_runner: ApplicationRunner | None,
+        health_checker: HealthChecker | None,
+    ) -> None:
+        self.command_environment = command_environment
+        self.command_runner = command_runner
+        self.application_runner = application_runner
+        self.health_checker = health_checker
+
+    def run(
+        self,
+        loaded: LoadedConfiguration,
+        *,
+        version: str,
+        config_path: Path,
+        operation_id: str,
+        store: StateStore,
+        lock: DeploymentLock,
+        cancellation_event: threading.Event | None,
+        stage_observer: CandidateStageObserver,
+    ) -> CandidateValidationResult:
+        return run_candidate_stage(
+            loaded,
+            version=version,
+            config_path=config_path,
+            operation_id=operation_id,
+            store=store,
+            lock=lock,
+            command_environment=self.command_environment,
+            command_runner=self.command_runner,
+            application_runner=self.application_runner,
+            health_checker=self.health_checker,
+            cancellation_event=cancellation_event,
+            complete_operation=False,
+            stage_observer=stage_observer,
+        )
+
+
+class ConfiguredCutoverDatabase:
+    def __init__(
+        self,
+        loaded: LoadedConfiguration,
+        *,
+        config_path: Path,
+        command_environment: Mapping[str, str],
+        command_runner: SubprocessRunner | None,
+    ) -> None:
+        self.loaded = loaded
+        self.config_path = config_path
+        self.command_environment = command_environment
+        self.command_runner = command_runner
+
+    def create_final(
+        self,
+        *,
+        operation_id: str,
+        stopped: ProductionStop,
+    ) -> BackupArtifact:
+        return create_final_backup(
+            self.loaded,
+            operation_id=operation_id,
+            stopped=stopped,
+        )
+
+    def migrate(
+        self,
+        *,
+        operation_id: str,
+        stopped: ProductionStop,
+        final_backup: BackupArtifact,
+        traffic_activated: bool,
+        evidence_sink: Callable[[MigrationCommandEvidence], None],
+        cancellation_event: threading.Event | None,
+        log_path: Path,
+    ) -> ProductionMigrationResult:
+        return migrate_production_database(
+            self.loaded,
+            operation_id=operation_id,
+            stopped=stopped,
+            final_backup=final_backup,
+            config_path=self.config_path,
+            traffic_activated=traffic_activated,
+            evidence_sink=evidence_sink,
+            command_environment=self.command_environment,
+            command_runner=self.command_runner,
+            cancellation_event=cancellation_event,
+            log_path=log_path,
+        )
+
+    def restore(
+        self,
+        *,
+        operation_id: str,
+        stopped: ProductionStop,
+        final_backup: BackupArtifact,
+        traffic_activated: bool,
+    ) -> VerifiedDatabaseRestoreResult:
+        return restore_final_backup(
+            self.loaded,
+            operation_id=operation_id,
+            stopped=stopped,
+            final_backup=final_backup,
+            traffic_activated=traffic_activated,
+        )
+
+
+class ConfiguredFinalBackupReplicator:
+    """Upload a final local backup through the configured S3-compatible target."""
+
+    def __init__(self, storage: RemoteBackupStorage) -> None:
+        self.storage = storage
+
+    def replicate(
+        self,
+        artifact: BackupArtifact,
+        *,
+        release_id: str,
+    ) -> RemoteBackupArtifact:
+        return self.storage.put(artifact, release_id=release_id)
+
+
+class ConfiguredPostActivationRetention:
+    """Apply the configured keep policy to local and optional remote storage."""
+
+    def __init__(
+        self,
+        *,
+        project: str,
+        keep_last: int,
+        local_storage: LocalBackupStorage,
+        remote_storage: RemoteBackupStorage | None,
+    ) -> None:
+        self.project = project
+        self.keep_last = keep_last
+        self.local_storage = local_storage
+        self.remote_storage = remote_storage
+
+    def apply(self, history: ReleaseHistorySnapshot) -> RetentionResult:
+        self.local_storage.ensure_layout()
+        return apply_retention(
+            project=self.project,
+            keep_last=self.keep_last,
+            history=history,
+            local_storage=self.local_storage,
+            remote_storage=self.remote_storage,
+        )
+
+
+def default_dependencies(
+    loaded: LoadedConfiguration,
+    *,
+    topology: ProductionTopology,
+    config_path: Path,
+    working_directory: Path,
+    command_environment: Mapping[str, str],
+    candidate_command_runner: SubprocessRunner | None,
+    candidate_application_runner: ApplicationRunner | None,
+    candidate_health_checker: HealthChecker | None,
+) -> tuple[DeploymentDependencies, ApplicationHealthChecker]:
+    production = DockerComposeProductionRunner(
+        project=loaded.config.project,
+        application=loaded.config.application,
+        topology=topology,
+        database_environment_name=loaded.config.database.path_env,
+        production_database_path=loaded.config.database.path,
+        secrets=loaded.secrets,
+        working_directory=working_directory,
+        command_environment=command_environment,
+    )
+    traffic = CommandTrafficController(
+        traffic=loaded.config.traffic,
+        secrets=loaded.secrets,
+        working_directory=working_directory,
+        command_environment=command_environment,
+    )
+    health = ApplicationHealthChecker(
+        application=loaded.config.application,
+        health_url=topology.health_url,
+        database_environment_name=loaded.config.database.path_env,
+        secrets=loaded.secrets,
+        working_directory=working_directory,
+        command_environment=command_environment,
+    )
+    remote_storage: RemoteBackupStorage | None = None
+    remote_backup: FinalBackupReplicator | None = None
+    remote_config = loaded.config.backup.remote
+    if remote_config is not None and remote_config.enabled:
+        remote_storage = configured_s3_storage(
+            remote_config,
+            secrets=loaded.secrets,
+            environment=command_environment,
+        )
+    if remote_config is not None and remote_config.required:
+        assert remote_storage is not None
+        remote_backup = ConfiguredFinalBackupReplicator(remote_storage)
+    retention = ConfiguredPostActivationRetention(
+        project=loaded.config.project,
+        keep_last=loaded.config.backup.keep_last,
+        local_storage=LocalBackupStorage(loaded.config.backup.local_directory),
+        remote_storage=remote_storage,
+    )
+    return (
+        DeploymentDependencies(
+            pre_cutover=ConfiguredPreCutover(
+                command_environment=command_environment,
+                command_runner=candidate_command_runner,
+                application_runner=candidate_application_runner,
+                health_checker=candidate_health_checker,
+            ),
+            production=production,
+            traffic=traffic,
+            database=ConfiguredCutoverDatabase(
+                loaded,
+                config_path=config_path,
+                command_environment=command_environment,
+                command_runner=None,
+            ),
+            health=health,
+            remote_backup=remote_backup,
+            retention=retention,
+        ),
+        health,
+    )

dploydb/deployment_evidence.py

@@ -0,0 +1,136 @@
+"""Typed compact release summaries and full operation evidence helpers."""
+
+from __future__ import annotations
+
+from typing import Literal, cast
+
+from dploydb.health import CandidateHealthResult
+from dploydb.models import BackupArtifact, ReleaseHealthEvidence, ReleaseHookEvidence
+from dploydb.redaction import JsonValue
+from dploydb.runners.base import (
+    ProductionCleanup,
+    ProductionDiscovery,
+    ProductionInspection,
+    ProductionRestart,
+    ProductionStart,
+    ProductionStop,
+)
+from dploydb.traffic import TrafficHookResult
+
+
+def hook_summary(result: TrafficHookResult) -> ReleaseHookEvidence:
+    command = result.command
+    return ReleaseHookEvidence(
+        action=result.action.value,
+        passed=result.passed,
+        outcome=command.outcome.value,
+        exit_code=command.exit_code,
+        output_complete=not command.stdout.truncated and not command.stderr.truncated,
+        duration_seconds=command.duration_seconds,
+        termination_reason=(
+            None if command.termination_reason is None else command.termination_reason.value
+        ),
+        forced_kill=command.forced_kill,
+        cleanup_error=command.cleanup_error,
+    )
+
+
+def health_summary(
+    result: CandidateHealthResult,
+    *,
+    role: Literal["new", "previous"],
+    version: str,
+) -> ReleaseHealthEvidence:
+    return ReleaseHealthEvidence(
+        role=role,
+        version=version,
+        url=result.readiness.url,
+        readiness_attempts=result.readiness.attempt_count,
+        smoke_outcome=None if result.smoke is None else "succeeded",
+    )
+
+
+def backup_evidence(artifact: BackupArtifact) -> dict[str, JsonValue]:
+    return {
+        "backup_id": artifact.metadata.backup_id,
+        "sha256": artifact.metadata.sha256,
+        "size_bytes": artifact.metadata.size_bytes,
+        "database_path": str(artifact.database_path),
+        "metadata_path": str(artifact.metadata_path),
+        "sqlite": cast(JsonValue, artifact.metadata.sqlite.model_dump(mode="json")),
+    }
+
+
+def inspection_evidence(inspection: ProductionInspection) -> dict[str, JsonValue]:
+    return {
+        "handle": cast(JsonValue, inspection.handle.model_dump(mode="json")),
+        "running": inspection.running,
+        "mounts": [
+            {
+                "mount_type": mount.mount_type,
+                "source": mount.source,
+                "destination": mount.destination,
+                "read_write": mount.read_write,
+            }
+            for mount in inspection.mounts
+        ],
+        "command": inspection.command.as_evidence(),
+    }
+
+
+def discovery_evidence(discovery: ProductionDiscovery) -> dict[str, JsonValue]:
+    return {
+        "query": discovery.query.as_evidence(),
+        "inspection": inspection_evidence(discovery.inspection),
+    }
+
+
+def stop_evidence(stopped: ProductionStop) -> dict[str, JsonValue]:
+    return {
+        "handle": cast(JsonValue, stopped.handle.model_dump(mode="json")),
+        "command": stopped.command.as_evidence(),
+        "inspection": inspection_evidence(stopped.inspection),
+    }
+
+
+def start_evidence(started: ProductionStart) -> dict[str, JsonValue]:
+    return {
+        "handle": cast(JsonValue, started.handle.model_dump(mode="json")),
+        "container_reference": started.container_reference,
+        "command": started.command.as_evidence(),
+        "inspection": inspection_evidence(started.inspection),
+    }
+
+
+def cleanup_evidence(cleanup: ProductionCleanup) -> dict[str, JsonValue]:
+    return {
+        "presence_query": cleanup.presence_query.as_evidence(),
+        "remove_command": (
+            None if cleanup.remove_command is None else cleanup.remove_command.as_evidence()
+        ),
+        "compose_down": cleanup.compose_down.as_evidence(),
+        "proof": {
+            "container_absent": cleanup.proof.container_absent,
+            "networks_absent": cleanup.proof.networks_absent,
+            "proven": cleanup.proof.proven,
+            "container_query": cleanup.proof.container_query.as_evidence(),
+            "network_query": cleanup.proof.network_query.as_evidence(),
+        },
+    }
+
+
+def restart_evidence(restarted: ProductionRestart) -> dict[str, JsonValue]:
+    return {
+        "handle": cast(JsonValue, restarted.handle.model_dump(mode="json")),
+        "network_refreshes": [
+            {
+                "network_name": refresh.network_name,
+                "aliases": list(refresh.aliases),
+                "disconnect": refresh.disconnect.as_evidence(),
+                "connect": refresh.connect.as_evidence(),
+            }
+            for refresh in restarted.network_refreshes
+        ],
+        "command": restarted.command.as_evidence(),
+        "inspection": inspection_evidence(restarted.inspection),
+    }