Implement WP-0011 hub service, CLI, and deployment artifacts

Add FederationHubAPI spec, hub registration schema, FastAPI hub with SQLite
persistence, reuse-surface hub CLI client, Dockerfile, and hub tests. Activate
workplan; T05 deploy and T06 ops docs remain open pending railiance01 cutover.

reuse_surface/hub/__init__.py

@@ -0,0 +1 @@
+"""Federation hub service package."""

reuse_surface/hub/app.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+from fastapi import Depends, FastAPI, Header, HTTPException, Query, Request
+from fastapi.responses import JSONResponse, Response
+
+from reuse_surface.hub.compose import compose_from_store, DEFAULT_DOMAIN
+from reuse_surface.hub.store import HubStore
+
+HUB_VERSION = "0.1.0"
+
+
+def _db_path() -> Path:
+    return Path(os.environ.get("REUSE_SURFACE_HUB_DB", "/data/hub.db"))
+
+
+def _cache_dir() -> Path:
+    return Path(os.environ.get("REUSE_SURFACE_HUB_CACHE_DIR", "/data/cache"))
+
+
+def _write_token() -> str:
+    return os.environ.get("REUSE_SURFACE_HUB_TOKEN", "")
+
+
+def _store() -> HubStore:
+    return HubStore(_db_path())
+
+
+def _http_error(status: int, error: str, message: str) -> HTTPException:
+    return HTTPException(
+        status_code=status,
+        detail={"error": error, "message": message, "details": []},
+    )
+
+
+def _require_auth(authorization: str | None = Header(default=None)) -> None:
+    write_token = _write_token()
+    if not write_token:
+        raise _http_error(
+            503, "misconfigured", "REUSE_SURFACE_HUB_TOKEN is not configured"
+        )
+    if not authorization or not authorization.startswith("Bearer "):
+        raise _http_error(401, "unauthorized", "Bearer token required")
+    token = authorization.removeprefix("Bearer ").strip()
+    if token != write_token:
+        raise _http_error(401, "unauthorized", "Invalid token")
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(title="reuse-surface federation hub", version=HUB_VERSION)
+    store = _store()
+
+    @app.get("/health")
+    def health() -> dict[str, str]:
+        return {"status": "ok", "service": "reuse-surface-hub", "version": HUB_VERSION}
+
+    @app.get("/v1/repos")
+    def list_repos() -> dict[str, Any]:
+        repos = store.list_repos()
+        return {"count": len(repos), "repos": repos}
+
+    @app.post("/v1/repos", status_code=201, dependencies=[Depends(_require_auth)])
+    async def register_repo(request: Request) -> dict[str, Any]:
+        payload = await request.json()
+        try:
+            return store.create_repo(payload)
+        except FileExistsError as exc:
+            raise _http_error(409, "conflict", str(exc)) from exc
+        except ValueError as exc:
+            raise _http_error(400, "validation_error", str(exc)) from exc
+
+    @app.get("/v1/repos/{repo}")
+    def get_repo(repo: str) -> dict[str, Any]:
+        registration = store.get_repo(repo)
+        if registration is None:
+            raise _http_error(404, "not_found", f"repo not found: {repo}")
+        return registration
+
+    @app.patch("/v1/repos/{repo}", dependencies=[Depends(_require_auth)])
+    async def update_repo(repo: str, request: Request) -> dict[str, Any]:
+        payload = await request.json()
+        try:
+            return store.update_repo(repo, payload)
+        except KeyError as exc:
+            raise _http_error(404, "not_found", str(exc)) from exc
+        except ValueError as exc:
+            raise _http_error(400, "validation_error", str(exc)) from exc
+
+    @app.delete("/v1/repos/{repo}", status_code=204, dependencies=[Depends(_require_auth)])
+    def delete_repo(repo: str) -> Response:
+        if not store.delete_repo(repo):
+            raise _http_error(404, "not_found", f"repo not found: {repo}")
+        return Response(status_code=204)
+
+    def _federated_response(
+        refresh: bool,
+        accept: str | None,
+        format_param: str,
+    ) -> Response:
+        try:
+            federated, warnings = compose_from_store(
+                store, refresh=refresh, cache_dir=_cache_dir(), domain=DEFAULT_DOMAIN
+            )
+        except FileNotFoundError as exc:
+            raise _http_error(502, "compose_error", str(exc)) from exc
+
+        use_yaml = format_param == "yaml" or (accept and "yaml" in accept.lower())
+        headers: dict[str, str] = {}
+        if warnings:
+            headers["X-Federation-Warnings"] = "; ".join(warnings)
+        if use_yaml:
+            body = yaml.safe_dump(federated, sort_keys=False)
+            return Response(content=body, media_type="application/yaml", headers=headers)
+        return JSONResponse(content=federated, headers=headers)
+
+    @app.get("/v1/federated", response_model=None)
+    def get_federated(
+        request: Request,
+        refresh: bool = Query(default=False),
+        format: str = Query(default="json"),
+    ) -> Response:
+        return _federated_response(refresh, request.headers.get("accept"), format)
+
+    @app.post("/v1/federated/compose", response_model=None, dependencies=[Depends(_require_auth)])
+    def compose_federated(
+        request: Request,
+        format: str = Query(default="json"),
+    ) -> Response:
+        return _federated_response(True, request.headers.get("accept"), format)
+
+    return app
+
+
+def main() -> None:
+    import uvicorn
+
+    host = os.environ.get("REUSE_SURFACE_HUB_HOST", "0.0.0.0")
+    port = int(os.environ.get("REUSE_SURFACE_HUB_PORT", "8000"))
+    uvicorn.run(create_app(), host=host, port=port, reload=False)

reuse_surface/hub/compose.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from reuse_surface.federation import compose_federated_index
+from reuse_surface.hub.store import HubStore
+
+DEFAULT_DOMAIN = os.environ.get("REUSE_SURFACE_HUB_DOMAIN", "helix_forge")
+
+
+def registrations_to_manifest(
+    registrations: list[dict[str, Any]],
+    *,
+    domain: str = DEFAULT_DOMAIN,
+) -> dict[str, Any]:
+    sources: list[dict[str, Any]] = []
+    for registration in registrations:
+        source: dict[str, Any] = {
+            "repo": registration["repo"],
+            "url": registration["url"],
+            "enabled": registration.get("enabled", True),
+            "required": registration.get("required", False),
+            "domain": registration.get("domain", domain),
+        }
+        if registration.get("description"):
+            source["description"] = registration["description"]
+        if registration.get("cache_ttl_seconds") is not None:
+            source["cache_ttl_seconds"] = registration["cache_ttl_seconds"]
+        if registration.get("auth_env"):
+            source["auth_env"] = registration["auth_env"]
+        if registration.get("auth_header"):
+            source["auth_header"] = registration["auth_header"]
+        sources.append(source)
+    return {
+        "version": 1,
+        "domain": domain,
+        "collision_policy": "warn",
+        "sources": sources,
+    }
+
+
+def compose_from_store(
+    store: HubStore,
+    *,
+    refresh: bool = False,
+    cache_dir: Path | None = None,
+    domain: str = DEFAULT_DOMAIN,
+) -> tuple[dict[str, Any], list[str]]:
+    manifest = registrations_to_manifest(store.list_repos_internal(), domain=domain)
+    return compose_federated_index(manifest, refresh=refresh, cache_dir=cache_dir)

reuse_surface/hub/store.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import yaml
+from jsonschema import Draft202012Validator
+
+from reuse_surface.registry import ROOT
+
+SCHEMA_PATH = ROOT / "schemas" / "hub-registration.schema.yaml"
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def _load_schema() -> dict[str, Any]:
+    return yaml.safe_load(SCHEMA_PATH.read_text(encoding="utf-8"))
+
+
+def _validate(payload: dict[str, Any], schema_ref: str) -> list[str]:
+    schema = _load_schema()
+    subschema = schema["$defs"][schema_ref]
+    validator = Draft202012Validator(subschema)
+    return [error.message for error in validator.iter_errors(payload)]
+
+
+def _row_to_registration(row: sqlite3.Row) -> dict[str, Any]:
+    data = json.loads(row["payload"])
+    data["registered_at"] = row["registered_at"]
+    data["updated_at"] = row["updated_at"]
+    return data
+
+
+def _public_registration(registration: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in registration.items() if key != "auth_env"}
+
+
+class HubStore:
+    def __init__(self, db_path: Path) -> None:
+        self.db_path = db_path
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _init_db(self) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS registrations (
+                    repo TEXT PRIMARY KEY,
+                    payload TEXT NOT NULL,
+                    registered_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                )
+                """
+            )
+
+    def list_repos(self) -> list[dict[str, Any]]:
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT * FROM registrations ORDER BY repo"
+            ).fetchall()
+        return [_public_registration(_row_to_registration(row)) for row in rows]
+
+    def get_repo(self, repo: str) -> dict[str, Any] | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT * FROM registrations WHERE repo = ?", (repo,)
+            ).fetchone()
+        if row is None:
+            return None
+        return _public_registration(_row_to_registration(row))
+
+    def get_repo_internal(self, repo: str) -> dict[str, Any] | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT * FROM registrations WHERE repo = ?", (repo,)
+            ).fetchone()
+        if row is None:
+            return None
+        return _row_to_registration(row)
+
+    def create_repo(self, payload: dict[str, Any]) -> dict[str, Any]:
+        errors = _validate(payload, "registration_request")
+        if errors:
+            raise ValueError("; ".join(errors))
+        now = _utc_now()
+        record: dict[str, Any] = {
+            "repo": payload["repo"],
+            "url": payload["url"],
+            "enabled": payload.get("enabled", True),
+            "required": payload.get("required", False),
+            "domain": payload["domain"],
+            "cache_ttl_seconds": payload.get("cache_ttl_seconds", 86400),
+            "auth_header": payload.get("auth_header", "Authorization"),
+        }
+        for optional in ("description", "auth_env", "registered_by"):
+            if payload.get(optional) is not None:
+                record[optional] = payload[optional]
+        validator = Draft202012Validator(_load_schema())
+        full_errors = [
+            error.message
+            for error in validator.iter_errors(
+                {**record, "registered_at": now, "updated_at": now}
+            )
+        ]
+        if full_errors:
+            raise ValueError("; ".join(full_errors))
+
+        with self._connect() as conn:
+            try:
+                conn.execute(
+                    """
+                    INSERT INTO registrations (repo, payload, registered_at, updated_at)
+                    VALUES (?, ?, ?, ?)
+                    """,
+                    (record["repo"], json.dumps(record), now, now),
+                )
+            except sqlite3.IntegrityError as exc:
+                raise FileExistsError(f"repo already registered: {record['repo']}") from exc
+        return _public_registration({**record, "registered_at": now, "updated_at": now})
+
+    def update_repo(self, repo: str, payload: dict[str, Any]) -> dict[str, Any]:
+        errors = _validate(payload, "registration_update")
+        if errors:
+            raise ValueError("; ".join(errors))
+        existing = self.get_repo_internal(repo)
+        if existing is None:
+            raise KeyError(f"repo not found: {repo}")
+        updated = {**existing, **{k: v for k, v in payload.items() if v is not None}, "repo": repo}
+        now = _utc_now()
+        updated["updated_at"] = now
+        with self._connect() as conn:
+            conn.execute(
+                """
+                UPDATE registrations
+                SET payload = ?, updated_at = ?
+                WHERE repo = ?
+                """,
+                (json.dumps(updated), now, repo),
+            )
+        return _public_registration(updated)
+
+    def delete_repo(self, repo: str) -> bool:
+        with self._connect() as conn:
+            cursor = conn.execute(
+                "DELETE FROM registrations WHERE repo = ?", (repo,)
+            )
+        return cursor.rowcount > 0
+
+    def list_repos_internal(self) -> list[dict[str, Any]]:
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT * FROM registrations ORDER BY repo"
+            ).fetchall()
+        return [_row_to_registration(row) for row in rows]