kleinkram 0.43.2.dev20250331124109__py3-none-any.whl → 0.58.0.dev20260110152317__py3-none-any.whl

kleinkram/api/routes.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 import json
+import tempfile
 from enum import Enum
+from pathlib import Path
 from typing import Any
 from typing import Dict
 from typing import Generator
@@ -12,6 +14,7 @@ from typing import Tuple
 from uuid import UUID
 
 import httpx
+import typer
 
 import kleinkram.errors
 from kleinkram._version import __version__
@@ -20,13 +23,17 @@ from kleinkram.api.client import AuthenticatedClient
 from kleinkram.api.deser import FileObject
 from kleinkram.api.deser import MissionObject
 from kleinkram.api.deser import ProjectObject
+from kleinkram.api.deser import RunObject
+from kleinkram.api.deser import _parse_action_template
 from kleinkram.api.deser import _parse_file
 from kleinkram.api.deser import _parse_mission
 from kleinkram.api.deser import _parse_project
+from kleinkram.api.deser import _parse_run
 from kleinkram.api.pagination import paginated_request
 from kleinkram.api.query import FileQuery
 from kleinkram.api.query import MissionQuery
 from kleinkram.api.query import ProjectQuery
+from kleinkram.api.query import RunQuery
 from kleinkram.api.query import file_query_is_unique
 from kleinkram.api.query import mission_query_is_unique
 from kleinkram.api.query import project_query_is_unique
@@ -38,12 +45,17 @@ from kleinkram.errors import InvalidMissionQuery
 from kleinkram.errors import InvalidProjectQuery
 from kleinkram.errors import MissionExists
 from kleinkram.errors import MissionNotFound
+from kleinkram.errors import MissionValidationError
 from kleinkram.errors import ProjectExists
 from kleinkram.errors import ProjectNotFound
+from kleinkram.errors import ProjectValidationError
+from kleinkram.models import ActionTemplate
 from kleinkram.models import File
 from kleinkram.models import Mission
 from kleinkram.models import Project
+from kleinkram.models import Run
 from kleinkram.utils import is_valid_uuid4
+from kleinkram.utils import split_args
 
 __all__ = [
     "_get_api_version",
@@ -79,6 +91,8 @@ PROJECT_ENDPOINT = "/projects"
 
 TAG_TYPE_BY_NAME = "/tag/filtered"
 
+ACTION_ENDPOINT = "/action"
+
 
 class Params(str, Enum):
     FILE_PATTERNS = "filePatterns"
@@ -137,9 +151,7 @@ def get_files(
     max_entries: Optional[int] = None,
 ) -> Generator[File, None, None]:
     params = _file_query_to_params(file_query)
-    response_stream = paginated_request(
-        client, FILE_ENDPOINT, params=params, max_entries=max_entries
-    )
+    response_stream = paginated_request(client, FILE_ENDPOINT, params=params, max_entries=max_entries)
     yield from map(lambda f: _parse_file(FileObject(f)), response_stream)
 
 
@@ -149,9 +161,7 @@ def get_missions(
     max_entries: Optional[int] = None,
 ) -> Generator[Mission, None, None]:
     params = _mission_query_to_params(mission_query)
-    response_stream = paginated_request(
-        client, MISSION_ENDPOINT, params=params, max_entries=max_entries
-    )
+    response_stream = paginated_request(client, MISSION_ENDPOINT, params=params, max_entries=max_entries)
     yield from map(lambda m: _parse_mission(MissionObject(m)), response_stream)
 
 
@@ -159,36 +169,93 @@ def get_projects(
     client: AuthenticatedClient,
     project_query: ProjectQuery,
     max_entries: Optional[int] = None,
+    exact_match: bool = False,
 ) -> Generator[Project, None, None]:
     params = _project_query_to_params(project_query)
     response_stream = paginated_request(
-        client, PROJECT_ENDPOINT, params=params, max_entries=max_entries
+        client,
+        PROJECT_ENDPOINT,
+        params=params,
+        max_entries=max_entries,
+        exact_match=exact_match,
     )
     yield from map(lambda p: _parse_project(ProjectObject(p)), response_stream)
 
 
-def get_project(client: AuthenticatedClient, query: ProjectQuery) -> Project:
+LIST_ACTIONS_ENDPOINT = "/actions"
+
+
+def get_runs(
+    client: AuthenticatedClient,
+    query: RunQuery,
+) -> Generator[Run, None, None]:
+
+    response_stream = paginated_request(client, LIST_ACTIONS_ENDPOINT)
+    yield from map(lambda p: _parse_run(RunObject(p)), response_stream)
+
+
+def get_run(
+    client: AuthenticatedClient,
+    run_id: str,
+) -> Run:
+    resp = client.get(f"{ACTION_ENDPOINT}s/{run_id}")
+    if resp.status_code == 404:
+        raise kleinkram.errors.RunNotFound(f"Run not found: {run_id}")
+    resp.raise_for_status()
+    return _parse_run(RunObject(resp.json()))
+
+
+def get_action_templates(
+    client: AuthenticatedClient,
+) -> Generator[ActionTemplate, None, None]:
+    response_stream = paginated_request(client, "/templates")
+    yield from map(lambda p: _parse_action_template(RunObject(p)), response_stream)
+
+
+def get_project(client: AuthenticatedClient, query: ProjectQuery, exact_match: bool = False) -> Project:
     """\
     get a unique project by specifying a project spec
     """
     if not project_query_is_unique(query):
-        raise InvalidProjectQuery(
-            f"Project query does not uniquely determine project: {query}"
-        )
+        raise InvalidProjectQuery(f"Project query does not uniquely determine project: {query}")
     try:
-        return next(get_projects(client, query))
+        return next(get_projects(client, query, exact_match=exact_match))
     except StopIteration:
         raise ProjectNotFound(f"Project not found: {query}")
 
 
+def submit_action(client: AuthenticatedClient, mission_uuid: UUID, template_uuid: UUID) -> str:
+    """
+    Submits a new action to the API and returns the action UUID.
+
+    Raises:
+        httpx.HTTPStatusError: If the API returns an error.
+        KeyError: If the response is missing 'actionUUID'.
+    """
+    submit_payload = {
+        "missionUUID": str(mission_uuid),
+        "templateUUID": str(template_uuid),
+    }
+
+    typer.echo("Submitting action...")
+    resp = client.post(f"{ACTION_ENDPOINT}s", json=submit_payload)
+    resp.raise_for_status()  # Raises on 4xx/5xx responses
+
+    response_data = resp.json()
+    action_uuid_str = response_data.get("actionUUID")
+
+    if not action_uuid_str:
+        raise KeyError("API response missing 'actionUUID'")
+
+    return action_uuid_str
+
+
 def get_mission(client: AuthenticatedClient, query: MissionQuery) -> Mission:
     """\
     get a unique mission by specifying a mission query
     """
     if not mission_query_is_unique(query):
-        raise InvalidMissionQuery(
-            f"Mission query does not uniquely determine mission: {query}"
-        )
+        raise InvalidMissionQuery(f"Mission query does not uniquely determine mission: {query}")
     try:
         return next(get_missions(client, query))
     except StopIteration:
@@ -207,12 +274,8 @@ def get_file(client: AuthenticatedClient, query: FileQuery) -> File:
         raise kleinkram.errors.FileNotFound(f"File not found: {query}")
 
 
-def _mission_name_is_available(
-    client: AuthenticatedClient, mission_name: str, project_id: UUID
-) -> bool:
-    mission_query = MissionQuery(
-        patterns=[mission_name], project_query=ProjectQuery(ids=[project_id])
-    )
+def _mission_name_is_available(client: AuthenticatedClient, mission_name: str, project_id: UUID) -> bool:
+    mission_query = MissionQuery(patterns=[mission_name], project_query=ProjectQuery(ids=[project_id]))
     try:
         _ = get_mission(client, mission_query)
     except MissionNotFound:
@@ -220,15 +283,68 @@ def _mission_name_is_available(
     return False
 
 
+def _validate_mission_name(client: AuthenticatedClient, project_id: UUID, mission_name: str) -> None:
+    if not _mission_name_is_available(client, mission_name, project_id):
+        raise MissionExists(f"Mission with name: `{mission_name}` already exists" f" in project: {project_id}")
+
+    if is_valid_uuid4(mission_name):
+        raise ValueError(f"Mission name: `{mission_name}` is a valid UUIDv4, " "mission names must not be valid UUIDv4's")
+
+    if mission_name.endswith(" "):
+        raise ValueError("A mission name cannot end with a whitespace. " f"The given mission name was '{mission_name}'")
+
+
 def _project_name_is_available(client: AuthenticatedClient, project_name: str) -> bool:
     project_query = ProjectQuery(patterns=[project_name])
     try:
-        _ = get_project(client, project_query)
+        _ = get_project(client, project_query, exact_match=True)
     except ProjectNotFound:
         return True
     return False
 
 
+def _validate_mission_created(client: AuthenticatedClient, project_id: str, mission_name: str) -> None:
+    """
+    validate that a mission is successfully created
+    """
+    mission_ids, mission_patterns = split_args([mission_name])
+    project_ids, project_patterns = split_args([project_id])
+
+    project_query = ProjectQuery(ids=project_ids, patterns=project_patterns)
+    mission_query = MissionQuery(
+        ids=mission_ids,
+        patterns=mission_patterns,
+        project_query=project_query,
+    )
+    try:
+        with tempfile.NamedTemporaryFile(suffix=".mcap", delete=False) as tmp:
+            tmp.write(b"dummy content")
+            tmp_path = Path(tmp.name)
+
+        kleinkram.core.upload(
+            client=client,
+            query=mission_query,
+            file_paths=[tmp_path],
+            verbose=False,
+        )
+
+        file_query = FileQuery(
+            ids=[],
+            patterns=[tmp_path.name],
+            mission_query=mission_query,
+        )
+        file_parsed = get_file(client, file_query)
+
+        kleinkram.core.delete_files(client=client, file_ids=[file_parsed.id])
+
+    except Exception as e:
+        raise MissionValidationError(f"Mission validation failed: {e}")
+
+    finally:
+        if tmp_path.exists():
+            tmp_path.unlink()
+
+
 def _create_mission(
     client: AuthenticatedClient,
     project_id: UUID,
@@ -236,6 +352,7 @@ def _create_mission(
     *,
     metadata: Optional[Dict[str, str]] = None,
     ignore_missing_tags: bool = False,
+    required_tags: Optional[List[str]] = None,
 ) -> UUID:
     """\
     creates a new mission with the given name and project_id
@@ -246,17 +363,10 @@ def _create_mission(
     if metadata is None:
         metadata = {}
 
-    if not _mission_name_is_available(client, mission_name, project_id):
-        raise MissionExists(
-            f"Mission with name: `{mission_name}` already exists"
-            f" in project: {project_id}"
-        )
+    _validate_mission_name(client, project_id, mission_name)
 
-    if is_valid_uuid4(mission_name):
-        raise ValueError(
-            f"Mission name: `{mission_name}` is a valid UUIDv4, "
-            "mission names must not be valid UUIDv4's"
-        )
+    if required_tags and not set(required_tags).issubset(metadata.keys()):
+        raise InvalidMissionMetadata(f"Mission tags `{required_tags}` are required but missing from metadata: {metadata}")
 
     # we need to translate tag keys to tag type ids
     tags = _get_tags_map(client, metadata)
@@ -267,20 +377,16 @@ def _create_mission(
         "tags": {str(k): v for k, v in tags.items()},
         "ignoreTags": ignore_missing_tags,
     }
-
     resp = client.post(CREATE_MISSION, json=payload)
     resp.raise_for_status()
+    _validate_mission_created(client, str(project_id), mission_name)
 
     return UUID(resp.json()["uuid"], version=4)
 
 
-def _create_project(
-    client: AuthenticatedClient, project_name: str, description: str
-) -> UUID:
-    if not _project_name_is_available(client, project_name):
-        raise ProjectExists(f"Project with name: `{project_name}` already exists")
+def _create_project(client: AuthenticatedClient, project_name: str, description: str) -> UUID:
 
-    # TODO: check name and description are valid
+    _validate_project_name(client, project_name, description)
     payload = {"name": project_name, "description": description}
     resp = client.post(CREATE_PROJECT, json=payload)
     resp.raise_for_status()
@@ -288,37 +394,60 @@ def _create_project(
     return UUID(resp.json()["uuid"], version=4)
 
 
-def _get_metadata_type_id_by_name(
-    client: AuthenticatedClient, tag_name: str
-) -> Optional[UUID]:
+def _validate_project_name(client: AuthenticatedClient, project_name: str, description: str) -> None:
+    if not _project_name_is_available(client, project_name):
+        raise ProjectExists(f"Project with name: `{project_name}` already exists")
+
+    if project_name.endswith(" "):
+        raise ProjectValidationError(f"Project name must not end with a tailing whitespace: `{project_name}`")
+
+    if not description:
+        raise ProjectValidationError("Project description is required")
+
+
+def _validate_tag_value(tag_value, tag_datatype) -> None:
+    if tag_datatype == "NUMBER":
+        try:
+            float(tag_value)
+        except ValueError:
+            raise InvalidMissionMetadata(f"Value '{tag_value}' is not a valid NUMBER")
+    elif tag_datatype == "BOOLEAN":
+        if tag_value.lower() not in {"true", "false"}:
+            raise InvalidMissionMetadata(f"Value '{tag_value}' is not a valid BOOLEAN (expected 'true' or 'false')")
+    else:
+        pass  # any string is fine
+    # TODO: add check for LOCATION tag datatype
+
+
+def _get_metadata_type_id_by_name(client: AuthenticatedClient, tag_name: str) -> Tuple[Optional[UUID], str]:
     resp = client.get(TAG_TYPE_BY_NAME, params={"name": tag_name, "take": 1})
 
     if resp.status_code in (403, 404):
         return None
 
     resp.raise_for_status()
+    try:
+        data = resp.json()["data"][0]
+    except IndexError:
+        return None, None
 
-    data = resp.json()[0]
-    return UUID(data["uuid"], version=4)
+    return UUID(data["uuid"], version=4), data["datatype"]
 
 
-def _get_tags_map(
-    client: AuthenticatedClient, metadata: Dict[str, str]
-) -> Dict[UUID, str]:
+def _get_tags_map(client: AuthenticatedClient, metadata: Dict[str, str]) -> Dict[UUID, str]:
     # TODO: this needs a better endpoint
     # why are we using metadata type ids as keys???
     ret = {}
     for key, val in metadata.items():
-        metadata_type_id = _get_metadata_type_id_by_name(client, key)
+        metadata_type_id, tag_datatype = _get_metadata_type_id_by_name(client, key)
         if metadata_type_id is None:
             raise InvalidMissionMetadata(f"metadata field: {key} does not exist")
+        _validate_tag_value(val, tag_datatype)
         ret[metadata_type_id] = val
     return ret
 
 
-def _update_mission(
-    client: AuthenticatedClient, mission_id: UUID, *, metadata: Dict[str, str]
-) -> None:
+def _update_mission(client: AuthenticatedClient, mission_id: UUID, *, metadata: Dict[str, str]) -> None:
     tags_dct = _get_tags_map(client, metadata)
     payload = {
         "missionUUID": str(mission_id),
@@ -357,12 +486,18 @@ def _get_api_version() -> Tuple[int, int, int]:
     config = get_config()
     client = httpx.Client()
 
-    resp = client.get(
-        f"{config.endpoint.api}{GET_STATUS}", headers={CLI_VERSION_HEADER: __version__}
-    )
-    vers = resp.headers["kleinkram-version"].split(".")
+    resp = client.get(f"{config.endpoint.api}{GET_STATUS}", headers={CLI_VERSION_HEADER: __version__})
+    vers_str = resp.headers.get("kleinkram-version")
 
-    return tuple(map(int, vers))  # type: ignore
+    if not vers_str:
+        return (0, 0, 0)
+
+    vers = vers_str.split(".")
+
+    try:
+        return tuple(map(int, vers))  # type: ignore
+    except ValueError:
+        return (0, 0, 0)
 
 
 def _claim_admin(client: AuthenticatedClient) -> None:
@@ -377,9 +512,7 @@ def _claim_admin(client: AuthenticatedClient) -> None:
 FILE_DELETE_MANY = "/files/deleteMultiple"
 
 
-def _delete_files(
-    client: AuthenticatedClient, file_ids: Sequence[UUID], mission_id: UUID
-) -> None:
+def _delete_files(client: AuthenticatedClient, file_ids: Sequence[UUID], mission_id: UUID) -> None:
     payload = {
         "uuids": [str(file_id) for file_id in file_ids],
         "missionUUID": str(mission_id),

kleinkram/auth.py

@@ -13,7 +13,7 @@ from kleinkram.config import get_config
 from kleinkram.config import save_config
 
 CLI_CALLBACK_ENDPOINT = "/cli/callback"
-OAUTH_SLUG = "/auth/google?state=cli"
+OAUTH_SLUG = "/auth/"
 
 
 def _has_browser() -> bool:
@@ -33,9 +33,7 @@ def _headless_auth(*, url: str) -> None:
 
     if auth_token and refresh_token:
         config = get_config()
-        config.credentials = Credentials(
-            auth_token=auth_token, refresh_token=refresh_token
-        )
+        config.credentials = Credentials(auth_token=auth_token, refresh_token=refresh_token)
         save_config(config)
         print(f"Authentication complete. Tokens saved to {CONFIG_PATH}.")
     else:
@@ -80,7 +78,89 @@ def _browser_auth(*, url: str) -> None:
     print(f"Authentication complete. Tokens saved to {CONFIG_PATH}.")
 
 
-def login_flow(*, key: Optional[str] = None, headless: bool = False) -> None:
+def _direct_oauth_auth(*, endpoint: str, provider: str, user: str) -> None:
+    """
+    Directly authenticate with fake OAuth by programmatically following the OAuth flow.
+    This bypasses the browser entirely for automated testing.
+    """
+    import requests
+
+    print(f"Authenticating as user {user} with {provider}...")
+
+    try:
+        # Step 1: Get the authorization code from fake OAuth
+        # The fake OAuth server will auto-redirect when user parameter is provided
+        fake_oauth_url = "http://localhost:8004/oauth/authorize"
+        callback_url = f"{endpoint}/auth/{provider}/callback"
+
+        params = {
+            "client_id": "some-random-string-it-does-not-matter",
+            "redirect_uri": callback_url,
+            "response_type": "code",
+            "state": "cli-direct",
+            "user": user,
+        }
+
+        # Make request to fake OAuth - it will redirect with the auth code
+        response = requests.get(fake_oauth_url, params=params, allow_redirects=False)
+
+        if response.status_code not in [301, 302, 303, 307, 308]:
+            raise RuntimeError(f"Expected redirect from OAuth provider, got {response.status_code}")
+
+        # Extract the redirect location
+        location = response.headers.get("Location")
+        if not location:
+            raise RuntimeError("No redirect location from OAuth provider")
+
+        # Parse the callback URL to extract the auth code
+        parsed = urllib.parse.urlparse(location)
+        query_params = urllib.parse.parse_qs(parsed.query)
+
+        if "code" not in query_params:
+            raise RuntimeError(f"No authorization code in redirect: {location}")
+
+        auth_code = query_params["code"][0]
+        state = query_params.get("state", [None])[0]
+
+        print("Received authorization code, exchanging for tokens...")
+
+        # Step 2: Exchange the code for tokens by calling the backend callback
+        # Use a session to preserve cookies
+        session = requests.Session()
+        callback_params = {"code": auth_code}
+        if state:
+            callback_params["state"] = state
+
+        callback_response = session.get(callback_url, params=callback_params, allow_redirects=False)
+
+        # The backend should set cookies and redirect
+        if callback_response.status_code not in [301, 302, 303, 307, 308]:
+            raise RuntimeError(f"Expected redirect from callback, got {callback_response.status_code}")
+
+        # Extract tokens from cookies
+        auth_token = session.cookies.get("authtoken")
+        refresh_token = session.cookies.get("refreshtoken")
+
+        if not auth_token or not refresh_token:
+            raise RuntimeError("Failed to get tokens from callback response")
+
+        # Save tokens
+        config = get_config()
+        config.credentials = Credentials(auth_token=auth_token, refresh_token=refresh_token)
+        save_config(config)
+        print(f"Authentication complete. Tokens saved to {CONFIG_PATH}.")
+
+    except requests.RequestException as e:
+        raise RuntimeError(f"OAuth flow failed: {e}")
+
+
+def login_flow(
+    *,
+    oAuthProvider: str,
+    key: Optional[str] = None,
+    headless: bool = False,
+    user: Optional[str] = None,
+) -> None:
     config = get_config()
     # use cli key login
     if key is not None:
@@ -88,8 +168,29 @@ def login_flow(*, key: Optional[str] = None, headless: bool = False) -> None:
         save_config(config)
         return
 
-    oauth_url = f"{config.endpoint.api}{OAUTH_SLUG}"
-    if not headless and _has_browser():
+    # If user parameter is provided with fake-oauth, use direct OAuth flow
+    if user is not None and oAuthProvider == "fake-oauth":
+        _direct_oauth_auth(endpoint=config.endpoint.api, provider=oAuthProvider, user=user)
+        return
+
+    # Build OAuth URL with state parameter
+    oauth_url = f"{config.endpoint.api}{OAUTH_SLUG}{oAuthProvider}?state=cli"
+
+    # Add user parameter if provided (for fake-oauth auto-login)
+    if user is not None:
+        oauth_url += f"&user={user}"
+
+    is_port_available = True
+    try:
+        server = HTTPServer(("", 8000), OAuthCallbackHandler)
+        server.server_close()
+    except OSError:
+        is_port_available = False
+
+    if not is_port_available:
+        print("Warning: Port 8000 is not available. Falling back to headless authentication.\n\n")
+
+    if not headless and _has_browser() and is_port_available:
         _browser_auth(url=oauth_url)
     else:
         _headless_auth(url=f"{oauth_url}-no-redirect")