compile-pdf-core 0.1.0__py3-none-any.whl

compile_pdf_core/__init__.py

@@ -0,0 +1,14 @@
+"""compile-pdf-core — shared infrastructure for the CompilePDF producer family.
+
+Provides lineage storage, retention consent, cache key computation,
+Celery task wrappers, queue-depth resolution, and API auth/middleware
+used by every CompilePDF producer (trap, impose, marks, rewrite).
+
+Producers import from this package rather than duplicating infra.
+"""
+
+from compile_pdf_core.version import VERSION
+
+__version__ = VERSION
+
+__all__ = ["VERSION", "__version__"]

compile_pdf_core/api/auth.py

@@ -0,0 +1,109 @@
+"""Authentication modes for compile-pdf API.
+
+Lifts the codex_pdf.api.auth surface verbatim per spec §1.10 — five modes
+selected via ``COMPILE_AUTH_MODE`` (comma-separated subset of
+``none``, ``bearer``, ``api-key``, ``internal``, ``basic``).
+
+Reuse rationale: codex's auth surface is already proven against the same
+threat model (internal calls + public-facing marketing demos). Lifting it
+verbatim minimizes new attack surface and keeps operator muscle memory
+uniform across codex/compile.
+"""
+
+from __future__ import annotations
+
+import os
+import secrets
+from collections.abc import Iterable
+
+from fastapi import HTTPException, Request, status
+
+ALL_MODES = frozenset({"none", "bearer", "api-key", "internal", "basic"})
+
+
+def get_active_modes() -> frozenset[str]:
+    """Read ``COMPILE_AUTH_MODE`` env var; default to ``none`` if unset."""
+    raw = os.environ.get("COMPILE_AUTH_MODE", "").strip()
+    if not raw:
+        return frozenset({"none"})
+    requested = {token.strip().lower() for token in raw.split(",") if token.strip()}
+    invalid = requested - ALL_MODES
+    if invalid:
+        raise RuntimeError(
+            f"COMPILE_AUTH_MODE contains unknown modes: {sorted(invalid)} "
+            f"(valid: {sorted(ALL_MODES)})"
+        )
+    return frozenset(requested)
+
+
+def _check_bearer(authorization: str | None) -> bool:
+    expected = os.environ.get("COMPILE_BEARER_TOKEN", "")
+    if not expected or not authorization:
+        return False
+    if not authorization.lower().startswith("bearer "):
+        return False
+    presented = authorization[len("Bearer ") :].strip()
+    return secrets.compare_digest(presented.encode(), expected.encode())
+
+
+def _check_api_key(api_key: str | None) -> bool:
+    expected = os.environ.get("COMPILE_API_KEY", "")
+    if not expected or not api_key:
+        return False
+    return secrets.compare_digest(api_key.encode(), expected.encode())
+
+
+def _check_internal(internal_token: str | None) -> bool:
+    expected = os.environ.get("COMPILE_INTERNAL_TOKEN", "")
+    if not expected or not internal_token:
+        return False
+    return secrets.compare_digest(internal_token.encode(), expected.encode())
+
+
+def _check_basic(authorization: str | None) -> bool:
+    if os.environ.get("COMPILE_BASIC_AUTH_ENABLED", "").lower() not in {"1", "true", "yes"}:
+        return False
+    expected_user = os.environ.get("COMPILE_BASIC_AUTH_USER", "")
+    expected_pass = os.environ.get("COMPILE_BASIC_AUTH_PASS", "")
+    if not expected_user or not expected_pass or not authorization:
+        return False
+    if not authorization.lower().startswith("basic "):
+        return False
+    import base64
+
+    try:
+        decoded = base64.b64decode(authorization[len("Basic ") :]).decode("utf-8")
+    except Exception:
+        return False
+    if ":" not in decoded:
+        return False
+    user, _, pwd = decoded.partition(":")
+    return secrets.compare_digest(user.encode(), expected_user.encode()) and secrets.compare_digest(
+        pwd.encode(), expected_pass.encode()
+    )
+
+
+def authenticate(request: Request, _modes: Iterable[str] | None = None) -> str:
+    """Dependency for FastAPI routes that require authentication.
+
+    Returns the mode that succeeded, raises 401 if all configured modes fail.
+    Healthcheck routes opt out by not declaring this dependency.
+    """
+    modes = frozenset(_modes) if _modes is not None else get_active_modes()
+    if "none" in modes:
+        return "none"
+
+    if "bearer" in modes and _check_bearer(request.headers.get("Authorization")):
+        return "bearer"
+    if "api-key" in modes and _check_api_key(request.headers.get("X-Compile-Key")):
+        return "api-key"
+    if "internal" in modes and _check_internal(request.headers.get("X-Compile-Internal")):
+        return "internal"
+    if "basic" in modes and _check_basic(request.headers.get("Authorization")):
+        return "basic"
+
+    raise HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="authentication required",
+        headers={"WWW-Authenticate": "Bearer"},
+    )

compile_pdf_core/api/middleware.py

@@ -0,0 +1,73 @@
+"""Request-id middleware mirroring codex-pdf 1.5's planned shape.
+
+Per spec §0 + IMPL-PLAN Phase 0 deliverable 0.2: every request gets a
+correlation ID that flows from upstream callers through compile to codex
+and back. ``X-Compile-Request-Id`` is the canonical header; missing IDs
+are generated fresh; the value is echoed in the response header and added
+to structured-log records.
+
+The same middleware also stamps ``X-Compile-Instance-Id`` on responses so
+operators can identify which replica answered the request during
+multi-instance rollouts.
+"""
+
+from __future__ import annotations
+
+import os
+import secrets
+import socket
+
+import structlog
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+def _resolve_instance_id() -> str:
+    """``COMPILE_INSTANCE_ID`` env var wins; falls back to hostname.
+
+    Used by both the middleware (response header) and the /healthz route.
+    """
+    explicit = os.environ.get("COMPILE_INSTANCE_ID", "").strip()
+    if explicit:
+        return explicit
+    return socket.gethostname() or "unknown"
+
+
+INSTANCE_ID = _resolve_instance_id()
+
+
+class RequestIdMiddleware(BaseHTTPMiddleware):
+    """Reads or generates ``X-Compile-Request-Id``, stores it on
+    ``request.state.request_id``, echoes in response headers, and binds it
+    to the structlog context so every log line correlates."""
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        request_id = (
+            request.headers.get("X-Compile-Request-Id")
+            or request.headers.get("x-compile-request-id")
+            or secrets.token_hex(8)
+        )
+        request.state.request_id = request_id
+
+        # Bind to structlog context so every log line during this request
+        # carries the request_id automatically.
+        structlog.contextvars.clear_contextvars()
+        structlog.contextvars.bind_contextvars(
+            request_id=request_id,
+            instance_id=INSTANCE_ID,
+            method=request.method,
+            path=request.url.path,
+        )
+        # Also propagate any upstream codex request-id we received so the
+        # full lint→compile→codex chain is queryable in logs.
+        upstream_codex_request_id = request.headers.get("X-Codex-Request-Id")
+        if upstream_codex_request_id:
+            structlog.contextvars.bind_contextvars(
+                upstream_codex_request_id=upstream_codex_request_id
+            )
+
+        response = await call_next(request)
+        response.headers["X-Compile-Request-Id"] = request_id
+        response.headers["X-Compile-Instance-Id"] = INSTANCE_ID
+        return response

compile_pdf_core/cache.py

@@ -0,0 +1,141 @@
+"""Cache key composition + plan canonicalization.
+
+Per spec §1.6 + §1.6a — cache key components (alphabetical-by-name so
+the digest is reproducible across language implementations):
+
+1. ``codex_document_schema_version``
+2. ``codex_pdf_package_version``
+3. ``color_schema_version``  (codex_pdf.color.COLOR_SCHEMA_VERSION)
+4. ``geom_schema_version``  (codex_pdf.geom.GEOM_SCHEMA_VERSION)
+5. ``compile_version``
+6. ``producer``  (rewrite | marks | impose | trap)
+7. ``sha256(canonical_plan)``
+8. ``sha256(input_bytes)``
+
+A Codex section bump auto-invalidates affected cached outputs (load-bearing
+operational property).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from decimal import ROUND_HALF_EVEN, Decimal
+from typing import Any
+
+from compile_pdf_core.version import VERSION as COMPILE_VERSION
+
+_PLAN_CANONICAL_NUMBER_QUANTIZE = Decimal("1E-12")
+"""Numeric precision used during canonicalization. 12 decimal places is enough
+to disambiguate prepress measurements (which rarely exceed ~5 decimals)
+without introducing float drift across Python/JS/Go implementations."""
+
+_DROPPED_KEYS = frozenset({"comment", "notes", "_dev_meta"})
+"""Keys stripped from canonical plan before hashing.
+Operators can decorate plans with these keys for human readability
+without the markings affecting the cache key."""
+
+
+def canonicalize_plan(plan: Mapping[str, Any] | list[Any] | str | int | float | bool | None) -> Any:
+    """Return a canonical, sortable, drop-null-decorated copy of a plan.
+
+    Canonicalization steps (per spec §2.2):
+
+    1. Sort all dict keys recursively.
+    2. Normalize numbers to fixed-decimal (round-half-even) so different
+       JSON serializers produce identical byte sequences.
+    3. Strip ``comment`` / ``notes`` / ``_dev_meta`` keys.
+    4. Drop ``None`` values (treat as absent).
+
+    Used by :func:`compute_cache_key`. Pure function; no I/O.
+    """
+    if plan is None:
+        return None
+    if isinstance(plan, bool):
+        # bool must be checked before int (bool is a subclass of int in Python).
+        return plan
+    if isinstance(plan, int):
+        return plan
+    if isinstance(plan, float):
+        # Round-half-even via Decimal so the digest is portable.
+        quantized = (
+            Decimal(repr(plan))
+            .quantize(_PLAN_CANONICAL_NUMBER_QUANTIZE, rounding=ROUND_HALF_EVEN)
+            .normalize()
+        )
+        as_str = format(quantized, "f")
+        # Re-parse so e.g. "1.0" stays a number in JSON, not a string.
+        try:
+            int_val = int(as_str)
+            if "." not in as_str:
+                return int_val
+        except ValueError:
+            pass
+        return float(as_str)
+    if isinstance(plan, str):
+        return plan
+    if isinstance(plan, list):
+        return [canonicalize_plan(item) for item in plan]
+    if isinstance(plan, Mapping):
+        return {
+            key: canonicalize_plan(value)
+            for key, value in sorted(plan.items())
+            if key not in _DROPPED_KEYS and value is not None
+        }
+    raise TypeError(f"Unsupported plan element type: {type(plan)!r}")
+
+
+def hash_canonical_plan(plan: Mapping[str, Any]) -> str:
+    """Return the SHA-256 of a canonicalized plan, hex-encoded.
+
+    The plan is canonicalized via :func:`canonicalize_plan` and then
+    serialized with ``json.dumps(..., separators=(",", ":"), ensure_ascii=False,
+    sort_keys=False)`` (sort_keys=False is safe because canonicalization already
+    sorted recursively).
+    """
+    canonical = canonicalize_plan(plan)
+    serialized = json.dumps(canonical, separators=(",", ":"), ensure_ascii=False)
+    return hashlib.sha256(serialized.encode("utf-8")).hexdigest()
+
+
+def compute_cache_key(
+    *,
+    producer: str,
+    input_sha256: str,
+    canonical_plan_sha256: str,
+    codex_pdf_package_version: str,
+    color_schema_version: str,
+    geom_schema_version: str,
+    codex_document_schema_version: str,
+    compile_version: str = COMPILE_VERSION,
+) -> str:
+    """Compose the per-job cache key.
+
+    Returns hex-encoded SHA-256. Components are concatenated alphabetical-by-name
+    with ``|`` separator so the digest is reproducible across implementations.
+
+    See spec §1.6a for the rationale on each component:
+
+    - ``codex_document_schema_version`` — top-level codex-document schema
+    - ``codex_pdf_package_version`` — catches Codex bug fixes without schema bump
+    - ``color_schema_version`` — invalidates on /v1/color/* changes
+    - ``geom_schema_version`` — invalidates on /v1/geom/* changes
+    - ``compile_version`` — captures Compile engine changes
+    - ``producer`` — distinguishes the four producer endpoints
+    - ``canonical_plan_sha256`` — plan hashed via :func:`hash_canonical_plan`
+    - ``input_sha256`` — sha256 of the raw input PDF bytes
+    """
+    components = "|".join(
+        [
+            codex_document_schema_version,
+            codex_pdf_package_version,
+            color_schema_version,
+            geom_schema_version,
+            compile_version,
+            producer,
+            canonical_plan_sha256,
+            input_sha256,
+        ]
+    )
+    return hashlib.sha256(components.encode("utf-8")).hexdigest()