cal-docs-server 3.0.0b1__py3-none-any.whl

cal_docs_server/api.py

@@ -0,0 +1,643 @@
+# ----------------------------------------------------------------------------------------
+#   api
+#   ---
+#
+#   REST API endpoints for cal-docs-server
+#
+#   License
+#   -------
+#   MIT License - Copyright 2025-2026 Cyber Assessment Labs
+#
+#   Authors
+#   -------
+#   bena (via Claude)
+#
+#   Version History
+#   ---------------
+#   Feb 2026 - Created
+# ----------------------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------------------
+#   Imports
+# ----------------------------------------------------------------------------------------
+
+import importlib.resources
+import io
+import json
+import os
+import re
+import urllib.parse
+import zipfile
+from datetime import datetime
+from functools import partial
+from typing import Any
+import yaml
+from aiohttp import web
+from aiohttp.multipart import BodyPartReader
+from . import async_file
+from . import auth
+from . import index_docs
+from .version import VERSION_STR
+
+# ----------------------------------------------------------------------------------------
+#   Constants
+# ----------------------------------------------------------------------------------------
+
+PRODUCT_NAME = "cal-docs-server"
+API_VERSION = "1.0"
+
+
+def _json_dumps(data: Any) -> str:
+    """JSON serializer with consistent formatting and trailing newline."""
+    return json.dumps(data, indent=2) + "\n"
+
+
+def _parse_docs_filename(filename: str) -> tuple[str, str] | None:
+    """
+    Parses a documentation zip filename to extract project name and version.
+
+    Handles formats like:
+      - cal-gitlab-mirror-0.3.1-docs.zip -> ("cal-gitlab-mirror", "0.3.1")
+      - caltech-6.5.0b5-documentation.zip -> ("caltech", "6.5.0b5")
+      - git-rewrite-0.8.1-docs.zip -> ("git-rewrite", "0.8.1")
+      - my-project-1.2.3.zip -> ("my-project", "1.2.3")
+
+    Returns (project, version) tuple or None if parsing fails.
+    """
+    # Must end with .zip
+    if not filename.lower().endswith(".zip"):
+        return None
+
+    # Strip .zip
+    name = filename[:-4]
+
+    # Strip common suffixes
+    for suffix in ["-docs", "-documentation", "-doc"]:
+        if name.lower().endswith(suffix):
+            name = name[: -len(suffix)]
+            break
+
+    # Find the version: look for last hyphen followed by a digit
+    # Version starts with a digit and can contain digits, dots, letters (like b1, rc1)
+    match = re.search(r"-(\d[^-]*)$", name)
+    if not match:
+        return None
+
+    version = match.group(1)
+    project = name[: match.start()]
+
+    # Validate we got something reasonable
+    if not project or not version:
+        return None
+
+    return (project, version)
+
+
+def _get_upload_filename(request: web.Request) -> str | None:
+    """
+    Best-effort filename extraction for application/zip uploads.
+
+    For multipart uploads, aiohttp provides `field.filename` and this helper is not used.
+    For raw uploads, accept either:
+      - X-Filename: my-project-1.2.3-docs.zip
+      - Content-Disposition: attachment; filename="my-project-1.2.3-docs.zip"
+      - Content-Disposition: attachment; filename*=UTF-8''my-project-1.2.3-docs.zip
+    """
+
+    header_filename = request.headers.get("X-Filename", "").strip()
+    if header_filename:
+        return os.path.basename(header_filename.strip('"'))
+
+    content_disposition = request.headers.get("Content-Disposition", "")
+    if not content_disposition:
+        return None
+
+    match = re.search(
+        r"filename\*=UTF-8''([^;]+)", content_disposition, flags=re.IGNORECASE
+    )
+    if match:
+        decoded = urllib.parse.unquote(match.group(1)).strip().strip('"')
+        return os.path.basename(decoded)
+
+    match = re.search(
+        r'filename="?([^";]+)"?', content_disposition, flags=re.IGNORECASE
+    )
+    if match:
+        return os.path.basename(match.group(1).strip())
+
+    return None
+
+
+# ----------------------------------------------------------------------------------------
+#   Functions
+# ----------------------------------------------------------------------------------------
+
+
+# ----------------------------------------------------------------------------------------
+def setup_api_routes(app: web.Application, root_directory: str) -> None:
+    """
+    Registers all API routes on the application.
+    """
+
+    app.router.add_get("/api/help", _handle_help)
+    app.router.add_get("/api/version", _handle_version)
+    app.router.add_get("/api/spec", _handle_spec)
+    app.router.add_get(
+        "/api/projects", partial(_handle_projects, root_directory=root_directory)
+    )
+    app.router.add_get(
+        "/api/download/{project}/{version}",
+        partial(_handle_download, root_directory=root_directory),
+    )
+    app.router.add_post(
+        "/api/upload", partial(_handle_upload, root_directory=root_directory)
+    )
+
+
+# ----------------------------------------------------------------------------------------
+#   Private Functions
+# ----------------------------------------------------------------------------------------
+
+API_HELP_TEMPLATE = """\
+CAL Documentation Server API
+=============================
+Version: {version}
+
+ENDPOINTS
+---------
+
+GET /api/help
+    This help text.
+
+GET /api/version
+    Returns server version as JSON.
+    Example: curl {base}/api/version
+
+GET /api/spec
+    Returns OpenAPI 3.0 specification as JSON.
+    Example: curl {base}/api/spec
+
+GET /api/projects
+    Lists all documentation projects and their versions.
+    Optional: ?search=term to filter by project name.
+    Example: curl {base}/api/projects
+    Example: curl "{base}/api/projects?search=myproject"
+
+GET /api/download/{{project}}/{{version}}
+    Downloads a project version as a .zip file.
+    Use "latest" as version for the most recent release.
+    Example: curl -o docs.zip {base}/api/download/myproject/1.0.0
+    Example: curl -o docs.zip {base}/api/download/myproject/latest
+
+POST /api/upload
+    Uploads documentation as a .zip file. Requires authentication.
+    Filename must be: {{project}}-{{version}}.zip or {{project}}-{{version}}-docs.zip
+    Example: curl -X POST -H "X-Token: YOUR_TOKEN" \\
+                  -F "file=@myproject-1.0.0-docs.zip" \\
+                  {base}/api/upload
+
+AUTHENTICATION
+--------------
+
+The upload endpoint requires a token via the X-Token header:
+
+    curl -H "X-Token: your-token-here" ...
+
+Tokens are configured server-side. Contact your administrator for access.
+
+CLIENT TOOL
+-----------
+
+For easier command-line access, install cal-docs-client:
+
+    pip install cal-docs-client
+    cal-docs-client --help
+
+For more information, see the OpenAPI spec at /api/spec
+"""
+
+
+# ----------------------------------------------------------------------------------------
+async def _handle_help(request: web.Request) -> web.Response:
+    """
+    GET /api/help
+    Returns human-readable API documentation.
+    """
+
+    base_url = request.app.get("base_url", "") or "http://example.com"
+    help_text = API_HELP_TEMPLATE.format(base=base_url, version=VERSION_STR)
+    return web.Response(text=help_text, content_type="text/plain")
+
+
+# ----------------------------------------------------------------------------------------
+async def _handle_version(_request: web.Request) -> web.Response:
+    """
+    GET /api/version
+    Returns product name and version as JSON.
+    """
+
+    return web.json_response(
+        dumps=_json_dumps,
+        data={
+            "product": PRODUCT_NAME,
+            "version": VERSION_STR,
+            "apiVersion": API_VERSION,
+        },
+    )
+
+
+# ----------------------------------------------------------------------------------------
+async def _handle_spec(_request: web.Request) -> web.Response:
+    """
+    GET /api/spec
+    Returns the OpenAPI 3.0 specification.
+    """
+
+    try:
+        file_folder = importlib.resources.files("cal_docs_server.resources")
+        file_path = os.path.join(str(file_folder), "openapi.yaml")
+
+        async with async_file.open_text(file_path, "r") as f:
+            spec_content = await f.read()
+
+        # Parse YAML and return as JSON for easier consumption
+        spec_dict = yaml.safe_load(spec_content)
+        return web.json_response(dumps=_json_dumps, data=spec_dict)
+    except Exception as e:
+        return web.json_response(
+            dumps=_json_dumps,
+            data={
+                "error": "Internal Server Error",
+                "message": f"Failed to load spec: {e}",
+            },
+            status=500,
+        )
+
+
+# ----------------------------------------------------------------------------------------
+async def _handle_projects(request: web.Request, root_directory: str) -> web.Response:
+    """
+    GET /api/projects
+    GET /api/projects?search=term
+
+    Returns list of all documentation projects and their versions.
+    Optional search parameter filters by project name (case-insensitive).
+    """
+
+    index_list = await index_docs.make_index(root_directory)
+
+    # Apply search filter if provided
+    search_term = request.query.get("search", "").lower().strip()
+    if search_term:
+        index_list = [
+            item
+            for item in index_list
+            if search_term in item["name"].lower()
+            or search_term in item["directory_name"].lower()
+        ]
+
+    # Prepend base_url to version URLs if configured
+    base_url = request.app.get("base_url", "")
+    if base_url:
+        for item in index_list:
+            for version in item["versions"]:
+                version["url"] = base_url + version["url"]
+                version["download_url"] = base_url + version["download_url"]
+
+    return web.json_response(
+        dumps=_json_dumps, data={"projects": index_list, "count": len(index_list)}
+    )
+
+
+# ----------------------------------------------------------------------------------------
+async def _handle_download(request: web.Request, root_directory: str) -> web.Response:
+    """
+    GET /api/download/{project}/{version}
+
+    Downloads a project version as a .zip file.
+    The {version} can be a specific version like "1.2.3" or "latest" for the latest version.
+    """
+
+    project = request.match_info.get("project", "")
+    version = request.match_info.get("version", "")
+
+    if not project or not version:
+        return web.json_response(
+            dumps=_json_dumps,
+            data={
+                "error": "Bad Request",
+                "message": "Project and version are required",
+            },
+            status=400,
+        )
+
+    # Validate no path traversal
+    if ".." in project or ".." in version:
+        return web.json_response(
+            dumps=_json_dumps,
+            data={"error": "Bad Request", "message": "Invalid project or version"},
+            status=400,
+        )
+
+    # Determine the directory to zip
+    if version.lower() == "latest":
+        # Find the latest version for this project
+        index_list = await index_docs.make_index(root_directory)
+        project_item = next(
+            (item for item in index_list if item["directory_name"] == project),
+            None,
+        )
+        if not project_item:
+            return web.json_response(
+                dumps=_json_dumps,
+                data={
+                    "error": "Not Found",
+                    "message": f"Project '{project}' not found",
+                },
+                status=404,
+            )
+
+        version_dir = project_item.get("latest_version_dir")
+        if not version_dir:
+            # No versioned directories, use base directory
+            version_dir = project
+    else:
+        # Specific version requested
+        version_dir = f"{project}-{version}"
+
+    dir_path = os.path.join(root_directory, version_dir)
+
+    if not os.path.isdir(dir_path):
+        return web.json_response(
+            dumps=_json_dumps,
+            data={
+                "error": "Not Found",
+                "message": f"Version '{version}' not found for project '{project}'",
+            },
+            status=404,
+        )
+
+    # Create zip in memory
+    zip_buffer = io.BytesIO()
+    with zipfile.ZipFile(zip_buffer, "w", zipfile.ZIP_DEFLATED) as zip_file:
+        for root, dirs, files in os.walk(dir_path):
+            # Skip hidden directories
+            dirs[:] = [d for d in dirs if not d.startswith(".")]
+
+            for file in files:
+                if file.startswith("."):
+                    continue
+                file_path = os.path.join(root, file)
+                arcname = os.path.relpath(file_path, dir_path)
+                zip_file.write(file_path, arcname)
+
+    zip_buffer.seek(0)
+    zip_filename = f"{version_dir}.zip"
+
+    return web.Response(
+        body=zip_buffer.getvalue(),
+        content_type="application/zip",
+        headers={"Content-Disposition": f'attachment; filename="{zip_filename}"'},
+    )
+
+
+# ----------------------------------------------------------------------------------------
+async def _handle_upload(request: web.Request, root_directory: str) -> web.Response:
+    """
+    POST /api/upload
+
+    Uploads a .zip file containing documentation.
+    Requires authentication via X-Token header.
+
+    The zip file should be sent as multipart/form-data with field name "file".
+    Alternative: raw zip bytes in request body with Content-Type: application/zip.
+    For raw uploads, include a filename via X-Filename or Content-Disposition.
+
+    curl example:
+        curl -X POST -H "X-Token: TOKEN" -F "file=@myproject-1.0.0-docs.zip" http://localhost/api/upload
+    """
+
+    # Check authentication
+    if error := auth.require_auth(request):
+        return error
+
+    zip_filename: str | None = None
+
+    # Handle multipart upload (form-data)
+    if request.content_type and request.content_type.startswith("multipart/"):
+        reader = await request.multipart()
+        field = await reader.next()
+
+        if field is None or not isinstance(field, BodyPartReader):
+            return web.json_response(
+                dumps=_json_dumps,
+                data={
+                    "error": "Bad Request",
+                    "message": "Missing 'file' field in form data",
+                },
+                status=400,
+            )
+
+        if field.name != "file":
+            return web.json_response(
+                dumps=_json_dumps,
+                data={
+                    "error": "Bad Request",
+                    "message": "Missing 'file' field in form data",
+                },
+                status=400,
+            )
+
+        # Get the original filename
+        zip_filename = field.filename
+
+        # Read the uploaded file
+        zip_data = await field.read(decode=False)
+
+    # Handle raw binary upload
+    elif request.content_type == "application/zip":
+        zip_filename = _get_upload_filename(request)
+        zip_data = await request.read()
+
+    else:
+        return web.json_response(
+            dumps=_json_dumps,
+            data={
+                "error": "Bad Request",
+                "message": "Expected multipart/form-data or application/zip",
+            },
+            status=400,
+        )
+
+    if not zip_data:
+        return web.json_response(
+            dumps=_json_dumps,
+            data={"error": "Bad Request", "message": "Empty file uploaded"},
+            status=400,
+        )
+
+    # Validate it's a valid zip file
+    try:
+        zip_buffer = io.BytesIO(zip_data)
+        with zipfile.ZipFile(zip_buffer, "r") as zip_file:
+            # Security: check for path traversal in zip entries
+            for name in zip_file.namelist():
+                if name.startswith("/") or ".." in name:
+                    return web.json_response(
+                        dumps=_json_dumps,
+                        data={
+                            "error": "Bad Request",
+                            "message": "Invalid file paths in zip",
+                        },
+                        status=400,
+                    )
+
+            # Parse filename to extract project and version
+            # e.g., "my-project-1.2.3-docs.zip" -> dir "my-project-1.2.3"
+            if not zip_filename:
+                return web.json_response(
+                    dumps=_json_dumps,
+                    data={
+                        "error": "Bad Request",
+                        "message": (
+                            "Filename is required. For multipart uploads, pass the file"
+                            " as form field 'file'. For raw application/zip uploads,"
+                            " provide a filename via X-Filename or Content-Disposition."
+                        ),
+                    },
+                    status=400,
+                )
+
+            parsed = _parse_docs_filename(zip_filename)
+            if not parsed:
+                return web.json_response(
+                    dumps=_json_dumps,
+                    data={
+                        "error": "Bad Request",
+                        "message": (
+                            "Could not parse project and version from filename."
+                            " Expected format: {project}-{version}.zip (optional"
+                            " suffixes: -docs, -documentation, -doc)"
+                        ),
+                    },
+                    status=400,
+                )
+
+            project, version = parsed
+            target_dir_name = f"{project}-{version}"
+
+            # Check if token is allowed to upload to this project
+            if not auth.check_project_allowed(request, project):
+                token_name = auth.get_token_name(request)
+                print(
+                    f"[{datetime.now():%Y-%m-%d %H:%M:%S}] Upload denied:"
+                    f" ip={request.remote} token={token_name} project={project}"
+                    f" version={version} reason=project_not_allowed"
+                )
+                return web.json_response(
+                    dumps=_json_dumps,
+                    data={
+                        "error": "Forbidden",
+                        "message": f"Token not authorized for project '{project}'",
+                    },
+                    status=403,
+                )
+
+            # Check if token is restricted to existing projects only
+            if auth.check_existing_projects_only(request):
+                # Check if any directory exists for this project
+                try:
+                    dir_list = os.listdir(root_directory)
+                except OSError:
+                    dir_list = []
+                project_exists = any(
+                    d == project or d.startswith(f"{project}-")
+                    for d in dir_list
+                    if os.path.isdir(os.path.join(root_directory, d))
+                )
+                if not project_exists:
+                    token_name = auth.get_token_name(request)
+                    print(
+                        f"[{datetime.now():%Y-%m-%d %H:%M:%S}] Upload denied:"
+                        f" ip={request.remote} token={token_name} project={project}"
+                        f" version={version} reason=new_project_not_allowed"
+                    )
+                    return web.json_response(
+                        dumps=_json_dumps,
+                        data={
+                            "error": "Forbidden",
+                            "message": (
+                                f"Project '{project}' does not exist and token "
+                                "does not have permission to create new projects"
+                            ),
+                        },
+                        status=403,
+                    )
+
+            # Validate directory name (no path traversal)
+            if ".." in target_dir_name or "/" in target_dir_name:
+                return web.json_response(
+                    dumps=_json_dumps,
+                    data={
+                        "error": "Bad Request",
+                        "message": "Invalid filename",
+                    },
+                    status=400,
+                )
+
+            target_dir = os.path.join(root_directory, target_dir_name)
+
+            # Check if directory exists and overwrite is not allowed
+            if os.path.exists(target_dir) and not auth.check_overwrite_allowed(request):
+                token_name = auth.get_token_name(request)
+                print(
+                    f"[{datetime.now():%Y-%m-%d %H:%M:%S}] Upload denied:"
+                    f" ip={request.remote} token={token_name} project={project}"
+                    f" version={version} reason=overwrite_not_allowed"
+                )
+                return web.json_response(
+                    dumps=_json_dumps,
+                    data={
+                        "error": "Forbidden",
+                        "message": (
+                            f"Directory '{target_dir_name}' already exists and "
+                            "token does not have overwrite permission"
+                        ),
+                    },
+                    status=403,
+                )
+
+            # Create target directory and extract
+            os.makedirs(target_dir, exist_ok=True)
+            zip_file.extractall(target_dir)
+            extracted_files = zip_file.namelist()
+
+            # Log successful upload
+            token_name = auth.get_token_name(request)
+            print(
+                f"[{datetime.now():%Y-%m-%d %H:%M:%S}] Upload: ip={request.remote}"
+                f" token={token_name} project={project} version={version}"
+                f" files={len(extracted_files)}"
+            )
+
+    except zipfile.BadZipFile:
+        return web.json_response(
+            dumps=_json_dumps,
+            data={"error": "Bad Request", "message": "Invalid zip file"},
+            status=400,
+        )
+
+    base_url = request.app.get("base_url", "")
+    return web.json_response(
+        dumps=_json_dumps,
+        data={
+            "success": True,
+            "message": "Documentation uploaded successfully",
+            "project": project,
+            "version": version,
+            "directory": target_dir_name,
+            "url": f"{base_url}/{target_dir_name}/",
+            "files_extracted": len(extracted_files),
+        },
+        status=201,
+    )