labrun-checks 0.2.0__tar.gz

labrun_checks-0.2.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: labrun-checks
+Version: 0.2.0
+Summary: Checkpoint validation for Labrun labs
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Requires-Dist: boto3>=1.26
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"

labrun_checks-0.2.0/README.md

@@ -0,0 +1,70 @@
+# labrun-checks
+
+Checkpoint validation and cleanup verification for labrun labs.
+
+## Install
+pip install labrun-checks
+
+## Usage in notebooks
+
+```python
+from labrun_checks import register, check, cleanup, run_cleanup
+from labrun_checks import CleanupResource
+
+# 1. Register session (called once in setup cell)
+register(
+    session_token=TOKEN,
+    lab_id="s3-raw-ingestion",
+    credentials={
+        "aws_access_key_id": AWS_KEY,
+        "aws_secret_access_key": AWS_SECRET,
+        "region": "us-east-1",
+    },
+)
+# credentials is optional. When provided, it attaches to the session and is
+# available inside checkpoint validators as session.credentials.
+
+# 2. Run checkpoint validations
+result = check(1, my_validator_fn)
+
+# 3. Run three-phase cleanup
+CLEANUP_MANIFEST = [
+    CleanupResource(type="s3_bucket", id="my-bucket", cli_delete_command="aws s3 rb s3://my-bucket --force"),
+    CleanupResource(type="glue_database", id="my_db", cli_delete_command="aws glue delete-database --name my_db"),
+]
+cleanup_result = run_cleanup(CLEANUP_MANIFEST)
+
+# 4. Report cleanup status
+cleanup(status=cleanup_result.status)
+```
+
+## Cleanup protocol
+
+`run_cleanup` implements the three-phase protocol from RESOURCE-SAFETY-SPEC Section 3.6:
+
+1. **Teardown**: Delete every resource in the manifest. Already-gone errors are swallowed. Other errors surface with the exact CLI command to run manually.
+2. **Verification**: Describe every resource to confirm deletion. Any resource still alive is reported.
+3. **Tag audit**: Query AWS Resource Groups Tagging API for resources tagged with this lab. Orphans from previous attempts are reported.
+
+Returns a `CleanupResult` with `status` ("clean" or "dirty"), `warnings`, and `orphans`.
+
+## Adapters
+
+The cleanup protocol uses dependency-injected adapters. `AwsCleanupAdapter` is the default. Custom adapters must implement the `CleanupAdapter` protocol:
+
+- `delete_resource(credentials, resource) -> None`
+- `describe_resource(credentials, resource) -> bool`
+- `tag_scan(credentials, lab_slug, region) -> list[str]`
+
+## Supported resource types
+
+- `s3_bucket`
+- `glue_database`
+- `glue_crawler`
+- `glue_table` (requires `parent` field for database name)
+- `kinesis_stream`
+- `iam_role` (detaches managed policies and deletes inline policies before deleting the role)
+
+## Version
+
+0.2.0

labrun_checks-0.2.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "labrun-checks"
+version = "0.2.0"
+description = "Checkpoint validation for Labrun labs"
+requires-python = ">=3.9"
+dependencies = [
+    "requests>=2.28",
+    "boto3>=1.26",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "responses>=0.23",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

labrun_checks-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

labrun_checks-0.2.0/src/labrun_checks/__init__.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import Callable
+
+from ._api import post_checkpoint, post_cleanup_complete
+from ._cleanup import run_cleanup
+from ._state import get_session, set_session
+from ._types import (
+    CheckpointResult,
+    CheckpointSession,
+    CleanupAdapter,
+    CleanupResource,
+    CleanupResult,
+)
+
+__all__ = [
+    "register",
+    "check",
+    "cleanup",
+    "run_cleanup",
+    "CheckpointResult",
+    "CheckpointSession",
+    "CleanupAdapter",
+    "CleanupResource",
+    "CleanupResult",
+]
+
+
+def register(session_token: str, lab_id: str, credentials: dict | None = None) -> None:
+    set_session(CheckpointSession(session_token=session_token, lab_id=lab_id, credentials=credentials or {}))
+
+
+def check(checkpoint_id: int, validator_fn: Callable[[CheckpointSession], CheckpointResult]) -> CheckpointResult:
+    session = get_session()
+
+    try:
+        result = validator_fn(session)
+    except Exception as exc:
+        result = CheckpointResult("error", error_reason=repr(exc))
+
+    try:
+        post_checkpoint(session.session_token, session.lab_id, checkpoint_id, result)
+    except Exception as exc:
+        return CheckpointResult(
+            "error",
+            error_reason=f"Network error recording checkpoint: {repr(exc)}",
+        )
+
+    return result
+
+
+def cleanup(status: str) -> CheckpointResult:
+    if status not in ("clean", "dirty"):
+        return CheckpointResult(
+            "error",
+            error_reason=f"status must be 'clean' or 'dirty', got {status!r}",
+        )
+
+    session = get_session()
+
+    try:
+        post_cleanup_complete(session.session_token, session.lab_id, status)
+    except Exception as exc:
+        return CheckpointResult(
+            "error",
+            error_reason=f"Network error posting cleanup event: {repr(exc)}",
+        )
+
+    return CheckpointResult("pass" if status == "clean" else "fail")

labrun_checks-0.2.0/src/labrun_checks/_api.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import os
+import time
+
+import requests
+
+from ._types import CheckpointResult
+
+_BASE_URL = os.environ.get("LABRUN_API_BASE_URL", "https://labrun.dev")
+
+
+def post_checkpoint(
+    session_token: str,
+    lab_id: str,
+    checkpoint_id: int,
+    result: CheckpointResult,
+) -> None:
+    payload = {
+        "lab_id": lab_id,
+        "checkpoint_id": checkpoint_id,
+        "status": result.status,
+        "timestamp": int(time.time()),
+    }
+    headers = {"Authorization": f"Bearer {session_token}"}
+    response = requests.post(
+        f"{_BASE_URL}/api/labs/checkpoint",
+        json=payload,
+        headers=headers,
+        timeout=10,
+    )
+    response.raise_for_status()
+
+
+def post_cleanup_complete(session_token: str, lab_id: str, status: str) -> None:
+    payload = {
+        "lab_id": lab_id,
+        "status": status,
+    }
+    headers = {"Authorization": f"Bearer {session_token}"}
+    response = requests.post(
+        f"{_BASE_URL}/api/labs/cleanup-complete",
+        json=payload,
+        headers=headers,
+        timeout=10,
+    )
+    response.raise_for_status()

labrun_checks-0.2.0/src/labrun_checks/_cleanup.py

@@ -0,0 +1,97 @@
+"""Three-phase cleanup orchestrator per RESOURCE-SAFETY-SPEC Section 3.6."""
+from __future__ import annotations
+
+from ._state import get_session
+from ._types import CleanupAdapter, CleanupResource, CleanupResult
+
+
+def run_cleanup(
+    manifest: list[CleanupResource],
+    adapter: CleanupAdapter | None = None,
+) -> CleanupResult:
+    """Run the three-phase cleanup protocol.
+
+    Args:
+        manifest: Resources to clean up, ordered critical-first.
+        adapter: Cloud adapter implementing delete/describe/tag_scan.
+                 Defaults to AwsCleanupAdapter if None.
+
+    Returns:
+        CleanupResult with status 'clean' or 'dirty', plus any warnings/orphans.
+    """
+    session = get_session()
+    lab_slug = session.lab_id
+
+    if adapter is None:
+        from .adapters.aws import AwsCleanupAdapter
+        adapter = AwsCleanupAdapter()
+
+    credentials = session.credentials
+    warnings: list[str] = []
+    orphans: list[str] = []
+
+    # Phase 1: Teardown
+    for resource in manifest:
+        try:
+            adapter.delete_resource(credentials, resource)
+        except Exception as exc:
+            cmd = resource.cli_delete_command or f"(no CLI command provided for {resource.type} {resource.id!r})"
+            warnings.append(
+                f"FAILED TO DELETE: {resource.type} {resource.id!r}. "
+                f"Error: {exc}. Run manually: {cmd}"
+            )
+
+    # Phase 2: Verification scan
+    for resource in manifest:
+        try:
+            still_exists = adapter.describe_resource(credentials, resource)
+        except Exception as exc:
+            warnings.append(
+                f"VERIFICATION ERROR: Could not check {resource.type} {resource.id!r}. "
+                f"Error: {exc}"
+            )
+            continue
+
+        if still_exists:
+            cmd = resource.cli_delete_command or f"(no CLI command provided for {resource.type} {resource.id!r})"
+            warnings.append(
+                f"WARNING: {resource.type} {resource.id!r} is still alive. "
+                f"Run this to kill it: {cmd}"
+            )
+
+    # Phase 3: Tag audit
+    region = credentials.get("region", "us-east-1")
+    manifest_ids = {r.id for r in manifest}
+    try:
+        tagged_arns = adapter.tag_scan(credentials, lab_slug, region)
+    except Exception as exc:
+        warnings.append(f"TAG AUDIT ERROR: Could not scan tags. Error: {exc}")
+        tagged_arns = []
+
+    for arn in tagged_arns:
+        resource_id = _extract_resource_id_from_arn(arn)
+        if resource_id not in manifest_ids:
+            orphans.append(
+                f"ORPHAN FOUND: {arn} is tagged as belonging to this lab "
+                f"but was not in this session's manifest. It may be left over "
+                f"from a previous attempt."
+            )
+
+    status = "clean" if (not warnings and not orphans) else "dirty"
+    return CleanupResult(status=status, warnings=warnings, orphans=orphans)
+
+
+def _extract_resource_id_from_arn(arn: str) -> str:
+    """Best-effort extraction of a human-readable resource ID from an ARN.
+
+    ARN formats vary by service:
+        arn:aws:s3:::bucket-name          -> bucket-name
+        arn:aws:glue:region:acct:database/db-name  -> db-name
+        arn:aws:kinesis:region:acct:stream/name     -> name
+    Falls back to the full ARN if no pattern matches.
+    """
+    if ":::" in arn:
+        return arn.split(":::")[-1]
+    if "/" in arn:
+        return arn.split("/")[-1]
+    return arn

labrun_checks-0.2.0/src/labrun_checks/_state.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from ._types import CheckpointSession
+
+_session: Optional[CheckpointSession] = None
+
+
+def get_session() -> CheckpointSession:
+    if _session is None:
+        raise RuntimeError(
+            "Call labrun_checks.register(session_token, lab_id) before using check() or cleanup()."
+        )
+    return _session
+
+
+def set_session(session: CheckpointSession) -> None:
+    global _session
+    _session = session
+
+
+def clear() -> None:
+    global _session
+    _session = None

labrun_checks-0.2.0/src/labrun_checks/_types.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, Optional, Protocol, runtime_checkable
+
+
+Status = Literal["pass", "fail", "error"]
+
+
+@dataclass
+class CheckpointResult:
+    status: Status
+    hint_tier_available: int = 0
+    error_reason: Optional[str] = None
+
+
+@dataclass
+class CheckpointSession:
+    session_token: str
+    lab_id: str
+    credentials: dict = field(default_factory=dict)
+
+
+@dataclass
+class CleanupResource:
+    """Single resource to be cleaned up. Ordering in manifest is critical-first."""
+    type: str
+    id: str
+    region: str = "us-east-1"
+    parent: Optional[str] = None
+    cli_delete_command: Optional[str] = None
+
+
+@dataclass
+class CleanupResult:
+    """Returned by run_cleanup. Notebook passes result.status to cleanup()."""
+    status: Literal["clean", "dirty"]
+    warnings: list[str] = field(default_factory=list)
+    orphans: list[str] = field(default_factory=list)
+
+
+@runtime_checkable
+class CleanupAdapter(Protocol):
+    """Interface that cloud-specific adapters must implement."""
+
+    def delete_resource(self, credentials: dict, resource: CleanupResource) -> None:
+        """Delete a single resource. Raise on failure. Swallow already-gone errors."""
+        ...
+
+    def describe_resource(self, credentials: dict, resource: CleanupResource) -> bool:
+        """Return True if resource still exists, False if confirmed gone."""
+        ...
+
+    def tag_scan(self, credentials: dict, lab_slug: str, region: str) -> list[str]:
+        """Return list of ARNs tagged with labrun:lab-slug=<lab_slug>."""
+        ...

labrun_checks-0.2.0/src/labrun_checks/adapters/__init__.py

@@ -0,0 +1,23 @@
+from .aws import (
+    AwsCleanupAdapter,
+    make_glue_client,
+    make_kinesis_client,
+    make_s3_client,
+    make_sts_client,
+    make_tagging_client,
+)
+from .azure import make_azure_resource_client
+from .databricks import make_databricks_client
+from .snowflake import make_snowflake_connection
+
+__all__ = [
+    "AwsCleanupAdapter",
+    "make_s3_client",
+    "make_glue_client",
+    "make_kinesis_client",
+    "make_sts_client",
+    "make_tagging_client",
+    "make_databricks_client",
+    "make_snowflake_connection",
+    "make_azure_resource_client",
+]

labrun_checks-0.2.0/src/labrun_checks/adapters/aws.py

@@ -0,0 +1,256 @@
+"""AWS boto3 adapter for labrun-checks checkpoints and cleanup."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+import boto3
+from botocore.exceptions import ClientError
+
+from .._types import CleanupResource
+
+if TYPE_CHECKING:
+    from mypy_boto3_s3 import S3Client
+
+
+_account_id_cache: Optional[str] = None
+
+
+def _make_client(service: str, credentials: dict):
+    return boto3.client(
+        service,
+        aws_access_key_id=credentials["aws_access_key_id"],
+        aws_secret_access_key=credentials["aws_secret_access_key"],
+        region_name=credentials.get("region", "us-east-1"),
+    )
+
+
+def make_s3_client(credentials: dict) -> "S3Client":
+    return _make_client("s3", credentials)
+
+
+def make_glue_client(credentials: dict):
+    return _make_client("glue", credentials)
+
+
+def make_kinesis_client(credentials: dict):
+    return _make_client("kinesis", credentials)
+
+
+def make_sts_client(credentials: dict):
+    return _make_client("sts", credentials)
+
+
+def make_tagging_client(credentials: dict):
+    return _make_client("resourcegroupstaggingapi", credentials)
+
+
+def make_iam_client(credentials: dict):
+    return _make_client("iam", credentials)
+
+
+def _get_account_id(credentials: dict) -> str:
+    global _account_id_cache
+    if _account_id_cache is None:
+        sts = make_sts_client(credentials)
+        _account_id_cache = sts.get_caller_identity()["Account"]
+    return _account_id_cache
+
+
+def clear_account_id_cache() -> None:
+    global _account_id_cache
+    _account_id_cache = None
+
+
+def _is_already_gone(exc: ClientError) -> bool:
+    code = exc.response.get("Error", {}).get("Code", "")
+    gone_codes = {
+        "NoSuchBucket",
+        "NoSuchKey",
+        "NoSuchEntity",
+        "EntityNotFoundException",
+        "ResourceNotFoundException",
+        "ResourceNotFoundFault",
+        "StreamNotFoundFault",
+    }
+    return code in gone_codes
+
+
+class AwsCleanupAdapter:
+    """Implements CleanupAdapter protocol for AWS resources."""
+
+    def delete_resource(self, credentials: dict, resource: CleanupResource) -> None:
+        try:
+            dispatcher = _DELETE_DISPATCH.get(resource.type)
+            if dispatcher is None:
+                raise ValueError(f"Unknown resource type: {resource.type!r}")
+            dispatcher(credentials, resource)
+        except ClientError as exc:
+            if _is_already_gone(exc):
+                return
+            raise
+
+    def describe_resource(self, credentials: dict, resource: CleanupResource) -> bool:
+        try:
+            dispatcher = _DESCRIBE_DISPATCH.get(resource.type)
+            if dispatcher is None:
+                raise ValueError(f"Unknown resource type: {resource.type!r}")
+            dispatcher(credentials, resource)
+            return True
+        except ClientError as exc:
+            if _is_already_gone(exc):
+                return False
+            raise
+
+    def tag_scan(self, credentials: dict, lab_slug: str, region: str) -> list[str]:
+        creds_with_region = {**credentials, "region": region}
+        client = make_tagging_client(creds_with_region)
+        tag_filters = [{"Key": "labrun:lab-slug", "Values": [lab_slug]}]
+        arns: list[str] = []
+        paginator = client.get_paginator("get_resources")
+        for page in paginator.paginate(TagFilters=tag_filters):
+            for item in page.get("ResourceTagMappingList", []):
+                arn = item.get("ResourceARN", "")
+                if _is_transitional_resource(creds_with_region, arn):
+                    continue
+                arns.append(arn)
+        return arns
+
+
+def _is_transitional_resource(credentials: dict, arn: str) -> bool:
+    """Phase 3 false-positive guard: skip resources in a deleting state."""
+    try:
+        if ":s3:::" in arn:
+            bucket_name = arn.split(":::")[-1]
+            s3 = make_s3_client(credentials)
+            s3.head_bucket(Bucket=bucket_name)
+            return False
+        if ":glue:" in arn and "/database/" in arn:
+            db_name = arn.split("/database/")[-1].split("/")[0]
+            glue = make_glue_client(credentials)
+            glue.get_database(Name=db_name)
+            return False
+    except ClientError as exc:
+        if _is_already_gone(exc):
+            return True
+    return False
+
+
+def _delete_s3_bucket(credentials: dict, resource: CleanupResource) -> None:
+    s3 = make_s3_client(credentials)
+    objects = s3.list_objects_v2(Bucket=resource.id)
+    for obj in objects.get("Contents", []):
+        s3.delete_object(Bucket=resource.id, Key=obj["Key"])
+    s3.delete_bucket(Bucket=resource.id)
+
+
+def _delete_glue_database(credentials: dict, resource: CleanupResource) -> None:
+    glue = make_glue_client(credentials)
+    glue.delete_database(Name=resource.id)
+
+
+def _delete_glue_crawler(credentials: dict, resource: CleanupResource) -> None:
+    glue = make_glue_client(credentials)
+    glue.delete_crawler(Name=resource.id)
+
+
+def _delete_glue_table(credentials: dict, resource: CleanupResource) -> None:
+    glue = make_glue_client(credentials)
+    if resource.parent is None:
+        raise ValueError(f"Glue table {resource.id!r} requires parent (database name)")
+    glue.delete_table(DatabaseName=resource.parent, Name=resource.id)
+
+
+def _delete_kinesis_stream(credentials: dict, resource: CleanupResource) -> None:
+    kinesis = make_kinesis_client(credentials)
+    kinesis.delete_stream(StreamName=resource.id, EnforceConsumerDeletion=True)
+
+
+def _delete_iam_role(credentials: dict, resource: CleanupResource) -> None:
+    iam = make_iam_client(credentials)
+    role_name = resource.id
+
+    try:
+        attached = iam.list_attached_role_policies(RoleName=role_name)
+    except ClientError as exc:
+        if _is_already_gone(exc):
+            return
+        raise
+    for policy in attached.get("AttachedPolicies", []):
+        try:
+            iam.detach_role_policy(RoleName=role_name, PolicyArn=policy["PolicyArn"])
+        except ClientError as exc:
+            if _is_already_gone(exc):
+                return
+            raise
+
+    try:
+        inline = iam.list_role_policies(RoleName=role_name)
+    except ClientError as exc:
+        if _is_already_gone(exc):
+            return
+        raise
+    for policy_name in inline.get("PolicyNames", []):
+        try:
+            iam.delete_role_policy(RoleName=role_name, PolicyName=policy_name)
+        except ClientError as exc:
+            if _is_already_gone(exc):
+                return
+            raise
+
+    try:
+        iam.delete_role(RoleName=role_name)
+    except ClientError as exc:
+        if _is_already_gone(exc):
+            return
+        raise
+
+
+def _describe_s3_bucket(credentials: dict, resource: CleanupResource) -> None:
+    s3 = make_s3_client(credentials)
+    s3.head_bucket(Bucket=resource.id)
+
+
+def _describe_glue_database(credentials: dict, resource: CleanupResource) -> None:
+    glue = make_glue_client(credentials)
+    glue.get_database(Name=resource.id)
+
+
+def _describe_glue_crawler(credentials: dict, resource: CleanupResource) -> None:
+    glue = make_glue_client(credentials)
+    glue.get_crawler(Name=resource.id)
+
+
+def _describe_glue_table(credentials: dict, resource: CleanupResource) -> None:
+    glue = make_glue_client(credentials)
+    if resource.parent is None:
+        raise ValueError(f"Glue table {resource.id!r} requires parent (database name)")
+    glue.get_table(DatabaseName=resource.parent, Name=resource.id)
+
+
+def _describe_kinesis_stream(credentials: dict, resource: CleanupResource) -> None:
+    kinesis = make_kinesis_client(credentials)
+    kinesis.describe_stream(StreamName=resource.id)
+
+
+def _describe_iam_role(credentials: dict, resource: CleanupResource) -> None:
+    iam = make_iam_client(credentials)
+    iam.get_role(RoleName=resource.id)
+
+
+_DELETE_DISPATCH = {
+    "s3_bucket": _delete_s3_bucket,
+    "glue_database": _delete_glue_database,
+    "glue_crawler": _delete_glue_crawler,
+    "glue_table": _delete_glue_table,
+    "kinesis_stream": _delete_kinesis_stream,
+    "iam_role": _delete_iam_role,
+}
+
+_DESCRIBE_DISPATCH = {
+    "s3_bucket": _describe_s3_bucket,
+    "glue_database": _describe_glue_database,
+    "glue_crawler": _describe_glue_crawler,
+    "glue_table": _describe_glue_table,
+    "kinesis_stream": _describe_kinesis_stream,
+    "iam_role": _describe_iam_role,
+}

labrun_checks-0.2.0/src/labrun_checks/adapters/azure.py

@@ -0,0 +1,9 @@
+"""Azure adapter stub for labrun-checks. Not yet implemented."""
+from __future__ import annotations
+
+
+def make_azure_resource_client(credentials: dict):
+    raise NotImplementedError(
+        "The Azure adapter is not yet available in labrun-checks. "
+        "Azure labs ship in a future release. Contact support@labrun.dev if this blocks you."
+    )

labrun_checks-0.2.0/src/labrun_checks/adapters/databricks.py

@@ -0,0 +1,9 @@
+"""Databricks adapter stub for labrun-checks. Not yet implemented."""
+from __future__ import annotations
+
+
+def make_databricks_client(credentials: dict):
+    raise NotImplementedError(
+        "The Databricks adapter is not yet available in labrun-checks. "
+        "Databricks labs ship in a future release. Contact support@labrun.dev if this blocks you."
+    )

labrun_checks-0.2.0/src/labrun_checks/adapters/snowflake.py

@@ -0,0 +1,9 @@
+"""Snowflake adapter stub for labrun-checks. Not yet implemented."""
+from __future__ import annotations
+
+
+def make_snowflake_connection(credentials: dict):
+    raise NotImplementedError(
+        "The Snowflake adapter is not yet available in labrun-checks. "
+        "Snowflake labs ship in a future release. Contact support@labrun.dev if this blocks you."
+    )

labrun_checks-0.2.0/src/labrun_checks.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: labrun-checks
+Version: 0.2.0
+Summary: Checkpoint validation for Labrun labs
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Requires-Dist: boto3>=1.26
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"

labrun_checks-0.2.0/src/labrun_checks.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+pyproject.toml
+src/labrun_checks/__init__.py
+src/labrun_checks/_api.py
+src/labrun_checks/_cleanup.py
+src/labrun_checks/_state.py
+src/labrun_checks/_types.py
+src/labrun_checks.egg-info/PKG-INFO
+src/labrun_checks.egg-info/SOURCES.txt
+src/labrun_checks.egg-info/dependency_links.txt
+src/labrun_checks.egg-info/requires.txt
+src/labrun_checks.egg-info/top_level.txt
+src/labrun_checks/adapters/__init__.py
+src/labrun_checks/adapters/aws.py
+src/labrun_checks/adapters/azure.py
+src/labrun_checks/adapters/databricks.py
+src/labrun_checks/adapters/snowflake.py
+tests/test_checks.py
+tests/test_cleanup.py

labrun_checks-0.2.0/src/labrun_checks.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

labrun_checks-0.2.0/src/labrun_checks.egg-info/requires.txt

@@ -0,0 +1,6 @@
+requests>=2.28
+boto3>=1.26
+
+[dev]
+pytest>=7
+responses>=0.23

labrun_checks-0.2.0/src/labrun_checks.egg-info/top_level.txt

@@ -0,0 +1 @@
+labrun_checks

labrun_checks-0.2.0/tests/test_checks.py

@@ -0,0 +1,287 @@
+"""
+Unit tests for labrun_checks public API.
+
+Covers:
+- Happy path: register -> check -> returns pass, POSTs correct payload
+- Fail path: validator returns fail, propagated correctly
+- Network-failure path: POST fails -> check returns error, not fail
+- Validator exception path: validator raises -> check returns error
+- Credentials never transmitted: POST body contains no credential values
+- cleanup(status='clean'): returns pass, posts to /api/labs/cleanup-complete
+- cleanup(status='dirty'): returns fail
+- cleanup(status=invalid): returns error without posting
+- cleanup payload regression: no event_type, no timestamp
+- cleanup network failure: returns error
+- cleanup HTTP error: returns error
+- Stubs raise NotImplementedError
+"""
+from __future__ import annotations
+
+from unittest.mock import MagicMock, call, patch
+
+import pytest
+import requests
+
+import labrun_checks
+from labrun_checks._types import CheckpointResult
+
+
+def _pass_validator(session):
+    return CheckpointResult("pass")
+
+
+def _fail_validator(session):
+    return CheckpointResult("fail", hint_tier_available=1)
+
+
+def _error_validator(session):
+    raise ConnectionError("boto3 network wobble")
+
+
+class TestRegisterAndCheck:
+    def test_register_stores_state(self):
+        labrun_checks.register("tok-123", "lab-01")
+        session = labrun_checks._state.get_session()
+        assert session.session_token == "tok-123"
+        assert session.lab_id == "lab-01"
+
+    def test_check_without_register_raises(self):
+        with pytest.raises(RuntimeError, match="register"):
+            labrun_checks.check(1, _pass_validator)
+
+    def test_happy_path_returns_pass(self):
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.return_value.raise_for_status = MagicMock()
+            result = labrun_checks.check(1, _pass_validator)
+
+        assert result.status == "pass"
+        assert result.hint_tier_available == 0
+        assert result.error_reason is None
+
+    def test_happy_path_posts_correct_payload(self):
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.return_value.raise_for_status = MagicMock()
+            labrun_checks.check(2, _pass_validator)
+
+        mock_post.assert_called_once()
+        _, kwargs = mock_post.call_args
+        body = kwargs["json"]
+        assert body["lab_id"] == "lab-01"
+        assert body["checkpoint_id"] == 2
+        assert body["status"] == "pass"
+        assert "timestamp" in body
+
+    def test_happy_path_sends_token_in_header_not_body(self):
+        labrun_checks.register("super-secret-token", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.return_value.raise_for_status = MagicMock()
+            labrun_checks.check(1, _pass_validator)
+
+        _, kwargs = mock_post.call_args
+        body = kwargs["json"]
+        assert "super-secret-token" not in str(body)
+        assert kwargs["headers"]["Authorization"] == "Bearer super-secret-token"
+
+    def test_credentials_never_transmitted(self):
+        # Deliberately non-AKIA placeholders so secret scanners (gitleaks,
+        # GitHub push protection) don't flag this test file. The values still
+        # exercise the "credentials must not leave the machine" assertion.
+        labrun_checks.register(
+            "tok-abc",
+            "lab-01",
+            credentials={
+                "aws_access_key_id": "TEST_KEY_ID_NOT_REAL_XYZ123",
+                "aws_secret_access_key": "TEST_SECRET_KEY_NOT_REAL_XYZ123_abcdefghij0123456789",
+            },
+        )
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.return_value.raise_for_status = MagicMock()
+            labrun_checks.check(1, _pass_validator)
+
+        _, kwargs = mock_post.call_args
+        serialized = str(kwargs["json"]) + str(kwargs.get("headers", {}))
+        assert "TEST_KEY_ID_NOT_REAL_XYZ123" not in serialized
+        assert "TEST_SECRET_KEY_NOT_REAL_XYZ123" not in serialized
+
+    def test_fail_validator_returns_fail(self):
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.return_value.raise_for_status = MagicMock()
+            result = labrun_checks.check(1, _fail_validator)
+
+        assert result.status == "fail"
+        assert result.hint_tier_available == 1
+
+    def test_network_failure_returns_error_not_fail(self):
+        """If the POST to our API fails, check() must return error, not fail."""
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.side_effect = requests.exceptions.ConnectionError("unreachable")
+            result = labrun_checks.check(1, _fail_validator)
+
+        assert result.status == "error"
+        assert result.status != "fail"
+
+    def test_network_failure_on_pass_returns_error(self):
+        """Even if validator passes, a POST failure yields error so student can retry."""
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.side_effect = requests.exceptions.Timeout("timeout")
+            result = labrun_checks.check(1, _pass_validator)
+
+        assert result.status == "error"
+
+    def test_validator_exception_returns_error(self):
+        """If the validator itself raises (e.g. boto3 network error), return error not fail."""
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.return_value.raise_for_status = MagicMock()
+            result = labrun_checks.check(1, _error_validator)
+
+        assert result.status == "error"
+        assert "ConnectionError" in result.error_reason
+
+    def test_validator_exception_still_posts(self):
+        """A validator exception should still POST the error status to the API."""
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.return_value.raise_for_status = MagicMock()
+            labrun_checks.check(1, _error_validator)
+
+        mock_post.assert_called_once()
+        _, kwargs = mock_post.call_args
+        assert kwargs["json"]["status"] == "error"
+
+
+def _mock_ok_response():
+    response = MagicMock()
+    response.status_code = 200
+    response.raise_for_status = MagicMock(return_value=None)
+    return response
+
+
+def _mock_http_error_response():
+    response = MagicMock()
+    response.status_code = 400
+    response.raise_for_status = MagicMock(
+        side_effect=requests.exceptions.HTTPError("400 Bad Request")
+    )
+    return response
+
+
+class TestCleanup:
+    def test_cleanup_clean_returns_pass(self):
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.return_value = _mock_ok_response()
+            result = labrun_checks.cleanup(status="clean")
+
+        assert result.status == "pass"
+
+    def test_cleanup_dirty_returns_fail(self):
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.return_value = _mock_ok_response()
+            result = labrun_checks.cleanup(status="dirty")
+
+        assert result.status == "fail"
+
+    def test_cleanup_invalid_status_returns_error_without_posting(self):
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            result = labrun_checks.cleanup(status="maybe")
+
+        assert result.status == "error"
+        mock_post.assert_not_called()
+        assert "must be 'clean' or 'dirty'" in result.error_reason
+
+    def test_cleanup_posts_correct_payload_for_clean(self):
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.return_value = _mock_ok_response()
+            labrun_checks.cleanup(status="clean")
+
+        mock_post.assert_called_once()
+        args, kwargs = mock_post.call_args
+        assert kwargs["json"] == {"lab_id": "lab-01", "status": "clean"}
+        url = args[0]
+        assert url.endswith("/api/labs/cleanup-complete")
+        assert "/api/labs/checkpoint" not in url
+        assert kwargs["headers"]["Authorization"] == "Bearer tok-abc"
+
+    def test_cleanup_posts_correct_payload_for_dirty(self):
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.return_value = _mock_ok_response()
+            labrun_checks.cleanup(status="dirty")
+
+        mock_post.assert_called_once()
+        args, kwargs = mock_post.call_args
+        assert kwargs["json"] == {"lab_id": "lab-01", "status": "dirty"}
+        url = args[0]
+        assert url.endswith("/api/labs/cleanup-complete")
+        assert "/api/labs/checkpoint" not in url
+        assert kwargs["headers"]["Authorization"] == "Bearer tok-abc"
+
+    def test_cleanup_payload_has_no_event_type_or_timestamp(self):
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.return_value = _mock_ok_response()
+            labrun_checks.cleanup(status="clean")
+
+        _, kwargs = mock_post.call_args
+        assert "event_type" not in kwargs["json"]
+        assert "timestamp" not in kwargs["json"]
+
+    def test_cleanup_network_failure_returns_error(self):
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.side_effect = requests.exceptions.ConnectionError("down")
+            result = labrun_checks.cleanup(status="clean")
+
+        assert result.status == "error"
+        assert "Network error" in result.error_reason
+
+    def test_cleanup_http_error_returns_error(self):
+        labrun_checks.register("tok-abc", "lab-01")
+
+        with patch("labrun_checks._api.requests.post") as mock_post:
+            mock_post.return_value = _mock_http_error_response()
+            result = labrun_checks.cleanup(status="clean")
+
+        assert result.status == "error"
+
+
+class TestAdapterStubs:
+    def test_databricks_stub_raises(self):
+        from labrun_checks.adapters.databricks import make_databricks_client
+        with pytest.raises(NotImplementedError, match="Databricks"):
+            make_databricks_client({})
+
+    def test_snowflake_stub_raises(self):
+        from labrun_checks.adapters.snowflake import make_snowflake_connection
+        with pytest.raises(NotImplementedError, match="Snowflake"):
+            make_snowflake_connection({})
+
+    def test_azure_stub_raises(self):
+        from labrun_checks.adapters.azure import make_azure_resource_client
+        with pytest.raises(NotImplementedError, match="Azure"):
+            make_azure_resource_client({})

labrun_checks-0.2.0/tests/test_cleanup.py

@@ -0,0 +1,270 @@
+"""Tests for run_cleanup: three-phase teardown/verify/tag-audit protocol."""
+from __future__ import annotations
+
+import pytest
+
+import labrun_checks
+from labrun_checks._types import CleanupResource, CleanupResult
+
+
+class FakeAdapter:
+    """Test double implementing CleanupAdapter protocol."""
+
+    def __init__(self):
+        self.deleted: list[str] = []
+        self.delete_side_effects: dict[str, Exception] = {}
+        self.describe_results: dict[str, bool] = {}
+        self.describe_side_effects: dict[str, Exception] = {}
+        self.tag_scan_result: list[str] = []
+        self.tag_scan_error: Exception | None = None
+
+    def delete_resource(self, credentials: dict, resource: CleanupResource) -> None:
+        if resource.id in self.delete_side_effects:
+            raise self.delete_side_effects[resource.id]
+        self.deleted.append(resource.id)
+
+    def describe_resource(self, credentials: dict, resource: CleanupResource) -> bool:
+        if resource.id in self.describe_side_effects:
+            raise self.describe_side_effects[resource.id]
+        return self.describe_results.get(resource.id, False)
+
+    def tag_scan(self, credentials: dict, lab_slug: str, region: str) -> list[str]:
+        if self.tag_scan_error is not None:
+            raise self.tag_scan_error
+        return self.tag_scan_result
+
+
+def _register_with_creds():
+    labrun_checks.register(
+        "tok-cleanup",
+        "s3-raw-ingestion",
+        credentials={
+            "aws_access_key_id": "TESTKEY",
+            "aws_secret_access_key": "TESTSECRET",
+            "region": "us-east-1",
+        },
+    )
+
+
+def _make_manifest():
+    return [
+        CleanupResource(
+            type="s3_bucket",
+            id="labrun-test-bucket",
+            cli_delete_command="aws s3 rb s3://labrun-test-bucket --force",
+        ),
+        CleanupResource(
+            type="glue_database",
+            id="labrun_test_db",
+            cli_delete_command="aws glue delete-database --name labrun_test_db",
+        ),
+    ]
+
+
+class TestRunCleanupHappyPath:
+    def test_all_clean_returns_clean(self):
+        _register_with_creds()
+        adapter = FakeAdapter()
+        result = labrun_checks.run_cleanup(_make_manifest(), adapter=adapter)
+
+        assert result.status == "clean"
+        assert result.warnings == []
+        assert result.orphans == []
+
+    def test_all_resources_deleted(self):
+        _register_with_creds()
+        adapter = FakeAdapter()
+        labrun_checks.run_cleanup(_make_manifest(), adapter=adapter)
+
+        assert "labrun-test-bucket" in adapter.deleted
+        assert "labrun_test_db" in adapter.deleted
+
+    def test_empty_manifest_returns_clean(self):
+        _register_with_creds()
+        adapter = FakeAdapter()
+        result = labrun_checks.run_cleanup([], adapter=adapter)
+
+        assert result.status == "clean"
+
+
+class TestRunCleanupWithoutRegister:
+    def test_raises_runtime_error(self):
+        adapter = FakeAdapter()
+        with pytest.raises(RuntimeError, match="register"):
+            labrun_checks.run_cleanup(_make_manifest(), adapter=adapter)
+
+
+class TestPhase1Teardown:
+    def test_delete_failure_returns_dirty_with_warning(self):
+        _register_with_creds()
+        adapter = FakeAdapter()
+        adapter.delete_side_effects["labrun-test-bucket"] = RuntimeError("AccessDenied")
+        result = labrun_checks.run_cleanup(_make_manifest(), adapter=adapter)
+
+        assert result.status == "dirty"
+        assert any("FAILED TO DELETE" in w for w in result.warnings)
+        assert any("labrun-test-bucket" in w for w in result.warnings)
+        assert any("aws s3 rb" in w for w in result.warnings)
+
+    def test_delete_failure_continues_to_next_resource(self):
+        _register_with_creds()
+        adapter = FakeAdapter()
+        adapter.delete_side_effects["labrun-test-bucket"] = RuntimeError("boom")
+        labrun_checks.run_cleanup(_make_manifest(), adapter=adapter)
+
+        assert "labrun_test_db" in adapter.deleted
+
+
+class TestPhase2Verification:
+    def test_resource_still_alive_returns_dirty(self):
+        _register_with_creds()
+        adapter = FakeAdapter()
+        adapter.describe_results["labrun-test-bucket"] = True
+        result = labrun_checks.run_cleanup(_make_manifest(), adapter=adapter)
+
+        assert result.status == "dirty"
+        assert any("still alive" in w for w in result.warnings)
+        assert any("aws s3 rb" in w for w in result.warnings)
+
+    def test_describe_error_returns_dirty(self):
+        _register_with_creds()
+        adapter = FakeAdapter()
+        adapter.describe_side_effects["labrun_test_db"] = RuntimeError("throttled")
+        result = labrun_checks.run_cleanup(_make_manifest(), adapter=adapter)
+
+        assert result.status == "dirty"
+        assert any("VERIFICATION ERROR" in w for w in result.warnings)
+
+
+class TestPhase3TagAudit:
+    def test_orphan_found_returns_dirty(self):
+        _register_with_creds()
+        adapter = FakeAdapter()
+        adapter.tag_scan_result = ["arn:aws:s3:::some-orphan-bucket"]
+        result = labrun_checks.run_cleanup(_make_manifest(), adapter=adapter)
+
+        assert result.status == "dirty"
+        assert len(result.orphans) == 1
+        assert "ORPHAN FOUND" in result.orphans[0]
+        assert "some-orphan-bucket" in result.orphans[0]
+
+    def test_manifest_resource_in_tag_scan_not_reported_as_orphan(self):
+        _register_with_creds()
+        adapter = FakeAdapter()
+        adapter.tag_scan_result = ["arn:aws:s3:::labrun-test-bucket"]
+        result = labrun_checks.run_cleanup(_make_manifest(), adapter=adapter)
+
+        assert result.status == "clean"
+        assert result.orphans == []
+
+    def test_tag_scan_error_returns_dirty(self):
+        _register_with_creds()
+        adapter = FakeAdapter()
+        adapter.tag_scan_error = RuntimeError("tagging API down")
+        result = labrun_checks.run_cleanup(_make_manifest(), adapter=adapter)
+
+        assert result.status == "dirty"
+        assert any("TAG AUDIT ERROR" in w for w in result.warnings)
+
+
+class TestAdapterDefault:
+    def test_none_adapter_imports_aws(self):
+        """When adapter=None, run_cleanup should try to instantiate AwsCleanupAdapter."""
+        _register_with_creds()
+        from unittest.mock import patch
+        with patch("labrun_checks.adapters.aws.AwsCleanupAdapter") as mock_cls:
+            mock_instance = FakeAdapter()
+            mock_cls.return_value = mock_instance
+            result = labrun_checks.run_cleanup(_make_manifest())
+
+        mock_cls.assert_called_once()
+        assert result.status == "clean"
+
+
+class TestCleanupResultShape:
+    def test_result_has_expected_fields(self):
+        _register_with_creds()
+        adapter = FakeAdapter()
+        adapter.describe_results["labrun-test-bucket"] = True
+        adapter.tag_scan_result = ["arn:aws:s3:::orphan-bucket"]
+        result = labrun_checks.run_cleanup(_make_manifest(), adapter=adapter)
+
+        assert isinstance(result, CleanupResult)
+        assert result.status == "dirty"
+        assert isinstance(result.warnings, list)
+        assert isinstance(result.orphans, list)
+        assert len(result.warnings) >= 1
+        assert len(result.orphans) >= 1
+
+
+class TestRegisterCredentials:
+    def test_register_with_credentials_kwarg(self):
+        from labrun_checks._state import get_session
+
+        creds = {
+            "aws_access_key_id": "TESTKEY",
+            "aws_secret_access_key": "TESTSECRET",
+            "region": "us-east-1",
+        }
+        labrun_checks.register("tok", "lab-1", credentials=creds)
+        session = get_session()
+        assert session.credentials == creds
+
+    def test_register_without_credentials_defaults_empty_dict(self):
+        from labrun_checks._state import get_session
+
+        labrun_checks.register("tok", "lab-1")
+        session = get_session()
+        assert session.credentials == {}
+
+
+class TestIamRoleAdapter:
+    def test_delete_iam_role_detaches_managed_and_deletes_inline_then_role(self):
+        from unittest.mock import MagicMock, patch
+
+        from labrun_checks._types import CleanupResource
+        from labrun_checks.adapters.aws import _delete_iam_role
+
+        iam = MagicMock()
+        iam.list_attached_role_policies.return_value = {
+            "AttachedPolicies": [{"PolicyArn": "arn:aws:iam::123:policy/managed-1"}],
+        }
+        iam.list_role_policies.return_value = {"PolicyNames": ["inline-1"]}
+
+        with patch("labrun_checks.adapters.aws.make_iam_client", return_value=iam):
+            resource = CleanupResource(type="iam_role", id="my-role")
+            _delete_iam_role({}, resource)
+
+        iam.detach_role_policy.assert_called_once_with(
+            RoleName="my-role",
+            PolicyArn="arn:aws:iam::123:policy/managed-1",
+        )
+        iam.delete_role_policy.assert_called_once_with(
+            RoleName="my-role",
+            PolicyName="inline-1",
+        )
+        iam.delete_role.assert_called_once_with(RoleName="my-role")
+
+    def test_describe_iam_role_calls_get_role(self):
+        from unittest.mock import MagicMock, patch
+
+        from labrun_checks._types import CleanupResource
+        from labrun_checks.adapters.aws import _describe_iam_role
+
+        iam = MagicMock()
+        with patch("labrun_checks.adapters.aws.make_iam_client", return_value=iam):
+            resource = CleanupResource(type="iam_role", id="my-role")
+            _describe_iam_role({}, resource)
+
+        iam.get_role.assert_called_once_with(RoleName="my-role")
+
+    def test_no_such_entity_is_already_gone(self):
+        from botocore.exceptions import ClientError
+
+        from labrun_checks.adapters.aws import _is_already_gone
+
+        exc = ClientError(
+            {"Error": {"Code": "NoSuchEntity", "Message": "Role not found"}},
+            "GetRole",
+        )
+        assert _is_already_gone(exc) is True