compile-pdf-core 0.1.0__tar.gz

compile_pdf_core-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,48 @@
+name: publish-pypi
+
+# Publishes compile-pdf-core to PyPI when a v*.*.* tag is pushed.
+#
+# Auth: PyPI Trusted Publishers (OIDC) — no API token in secrets.
+# Configure once at https://pypi.org/manage/account/publishing/ with:
+#   - PyPI project: compile-pdf-core
+#   - Owner:        printwithsynergy
+#   - Repository:   compile-pdf-core
+#   - Workflow:     publish-pypi.yml
+#   - Environment:  release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install --upgrade pip build
+      - run: python -m build --sdist --wheel --outdir dist/
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/project/compile-pdf-core/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

compile_pdf_core-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: compile-pdf-core
+Version: 0.1.0
+Summary: CompilePDF core — shared lineage, retention, cache, auth, and task infrastructure for the CompilePDF producer family.
+Project-URL: Homepage, https://compilepdf.com
+Project-URL: Repository, https://github.com/printwithsynergy/compile-pdf-core
+Project-URL: Issues, https://github.com/printwithsynergy/compile-pdf-core/issues
+Author-email: Print With Synergy <iam@quincy.codes>
+License: AGPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: boto3>=1.34
+Requires-Dist: celery[redis]>=5.3
+Requires-Dist: click>=8.1
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: prometheus-client>=0.20
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: redis>=5.0
+Requires-Dist: structlog>=24.1
+Requires-Dist: ulid-py>=1.1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-redis; extra == 'dev'

compile_pdf_core-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[project]
+name = "compile-pdf-core"
+version = "0.1.0"
+description = "CompilePDF core — shared lineage, retention, cache, auth, and task infrastructure for the CompilePDF producer family."
+readme = "README.md"
+license = { text = "AGPL-3.0-or-later" }
+authors = [{ name = "Print With Synergy", email = "iam@quincy.codes" }]
+requires-python = ">=3.12"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Multimedia :: Graphics",
+  "Topic :: Software Development :: Libraries",
+]
+
+dependencies = [
+  "fastapi>=0.110",
+  "pydantic>=2.6",
+  "pydantic-settings>=2.2",
+  "celery[redis]>=5.3",
+  "redis>=5.0",
+  "boto3>=1.34",
+  "httpx>=0.27",
+  "click>=8.1",
+  "structlog>=24.1",
+  "prometheus-client>=0.20",
+  "ulid-py>=1.1",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "pytest-cov>=4.1",
+  "ruff>=0.4",
+  "mypy>=1.9",
+  "types-redis",
+]
+
+[project.urls]
+Homepage = "https://compilepdf.com"
+Repository = "https://github.com/printwithsynergy/compile-pdf-core"
+Issues = "https://github.com/printwithsynergy/compile-pdf-core/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/compile_pdf_core"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "C4", "RET"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["N802", "N803"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+plugins = ["pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+module = ["boto3", "boto3.*", "celery", "celery.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["src/compile_pdf_core"]
+branch = true

compile_pdf_core-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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()