hawser-server 0.1.0__py3-none-any.whl

hawser_server/__init__.py

@@ -0,0 +1,11 @@
+"""Hawser control plane: ``hawserd`` (ADR-0010)."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("hawser-server")
+except PackageNotFoundError:  # running from a source tree without installed metadata
+    __version__ = "0.1.0"
+
+__all__ = ["__version__"]

hawser_server/app.py

@@ -0,0 +1,115 @@
+"""The FastAPI application. ``create_app(services)`` wires routes, errors and request ids."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Awaitable, Callable
+from importlib import resources
+from pathlib import Path
+
+from fastapi import FastAPI, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, RedirectResponse
+
+from hawser.models import CONTRACT_VERSION
+from hawser_server import __version__
+from hawser_server.errors import install_error_handlers
+from hawser_server.routes import (
+    approvals,
+    artifacts,
+    assets,
+    catalog,
+    evals,
+    examples,
+    reviews,
+    runs,
+    settings,
+    system,
+    webhooks,
+)
+from hawser_server.services import Services
+
+DESCRIPTION = (
+    "Hawser control plane. Bodies and responses are the contract models published under "
+    "`api/schemas/`; errors are `application/problem+json` with the error-taxonomy `code`."
+)
+
+
+def create_app(services: Services) -> FastAPI:
+    app = FastAPI(
+        title="Hawser API",
+        version=f"{CONTRACT_VERSION}+hawserd.{__version__}",
+        description=DESCRIPTION,
+        docs_url="/docs",
+        openapi_url="/openapi.json",
+    )
+    app.state.services = services
+    install_error_handlers(app)
+
+    @app.middleware("http")
+    async def _request_id(
+        request: Request, call_next: Callable[[Request], Awaitable[Response]]
+    ) -> Response:
+        rid = request.headers.get("X-Hawser-Request-Id") or f"req_{uuid.uuid4().hex[:20]}"
+        request.state.request_id = rid
+        response = await call_next(request)
+        response.headers["X-Hawser-Request-Id"] = rid
+        return response
+
+    if services.config.cors_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=services.config.cors_origins,
+            allow_methods=["*"],
+            allow_headers=["*"],
+            expose_headers=["ETag", "Location", "X-Hawser-Request-Id", "X-Hawser-Dpi"],
+        )
+
+    for r in (
+        system,
+        assets,
+        runs,
+        reviews,
+        approvals,
+        catalog,
+        artifacts,
+        webhooks,
+        evals,
+        settings,
+        examples,
+    ):
+        app.include_router(r.router)
+    _mount_web(app, services.config.web_dir)
+    return app
+
+
+def web_dir(configured: Path | None) -> Path | None:
+    """The built web app: an explicit directory, else the package's ``static`` folder."""
+    if configured is not None:
+        return configured if (configured / "index.html").exists() else None
+    with resources.as_file(resources.files("hawser_server") / "static") as path:
+        bundled = Path(path)
+    return bundled if (bundled / "index.html").exists() else None
+
+
+def _mount_web(app: FastAPI, configured: Path | None) -> None:
+    root = web_dir(configured)
+    if root is None:
+        return
+    index = root / "index.html"
+
+    @app.get("/", include_in_schema=False)
+    async def _root() -> RedirectResponse:
+        return RedirectResponse("/app/")
+
+    @app.get("/app", include_in_schema=False)
+    @app.get("/app/{path:path}", include_in_schema=False)
+    async def _app(path: str = "") -> FileResponse:
+        # Single-page app: real files are served as-is, every other path gets index.html.
+        candidate = (root / path).resolve() if path else index
+        if path and candidate.is_file() and root.resolve() in candidate.parents:
+            return FileResponse(candidate)
+        return FileResponse(index)
+
+
+__all__ = ["create_app"]

hawser_server/auth.py

@@ -0,0 +1,187 @@
+"""API keys and tenants.
+
+Keys are ``hk_live_<40 url-safe chars>``, shown once, stored as an argon2id hash. Lookup is by
+a short hash prefix (so any token shape works for ``HAWSERD_DEV_API_KEY``), then a full verify.
+Verified tokens are cached in memory for a few minutes to keep argon2 off the request path.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+import threading
+import time
+from dataclasses import dataclass
+
+from argon2 import PasswordHasher
+from argon2.exceptions import VerificationError
+
+from hawser.config import LOCAL_TENANT
+from hawser.ids import new_id
+from hawser.storage.sql import SqlBackend
+from hawser_server.util import ts
+
+KEY_PREFIX = "hk_live_"
+_CACHE_TTL_S = 300.0
+
+
+@dataclass(frozen=True)
+class Principal:
+    tenant_id: str
+    key_id: str
+
+
+@dataclass(frozen=True)
+class Tenant:
+    id: str
+    name: str
+    created_at: str
+
+
+@dataclass(frozen=True)
+class ApiKey:
+    id: str
+    tenant_id: str
+    name: str
+    prefix: str
+    created_at: str
+    revoked_at: str | None
+    last_used_at: str | None
+
+
+def _prefix(token: str) -> str:
+    return hashlib.sha256(token.encode()).hexdigest()[:16]
+
+
+def generate_key() -> str:
+    return KEY_PREFIX + secrets.token_urlsafe(30)[:40]
+
+
+class AuthService:
+    def __init__(self, backend: SqlBackend) -> None:
+        self.backend = backend
+        self.hasher = PasswordHasher()
+        self._cache: dict[str, tuple[Principal, float]] = {}
+        self._lock = threading.Lock()
+
+    # -- tenants ---------------------------------------------------------------------------
+    def create_tenant(self, name: str, *, tenant_id: str | None = None) -> Tenant:
+        tenant = Tenant(id=tenant_id or new_id("ten"), name=name, created_at=ts())
+        with self.backend.transaction(write=True) as tx:
+            tx.execute(
+                "INSERT INTO tenants (id, name, created_at) VALUES (?,?,?) ON CONFLICT DO NOTHING",
+                (tenant.id, tenant.name, tenant.created_at),
+            )
+        return tenant
+
+    def get_tenant(self, tenant_id: str) -> Tenant | None:
+        with self.backend.transaction() as tx:
+            rows = tx.execute("SELECT id, name, created_at FROM tenants WHERE id = ?", (tenant_id,))
+        return None if not rows else Tenant(*(str(c) for c in rows[0]))
+
+    def list_tenants(self) -> list[Tenant]:
+        with self.backend.transaction() as tx:
+            rows = tx.execute("SELECT id, name, created_at FROM tenants ORDER BY created_at")
+        return [Tenant(*(str(c) for c in r)) for r in rows]
+
+    # -- keys ------------------------------------------------------------------------------
+    def create_key(
+        self, tenant_id: str, name: str, *, token: str | None = None
+    ) -> tuple[ApiKey, str]:
+        """Create a key; returns the record and the plaintext token (shown once)."""
+        if self.get_tenant(tenant_id) is None:
+            raise KeyError(tenant_id)
+        token = token or generate_key()
+        key = ApiKey(
+            id=new_id("key"),
+            tenant_id=tenant_id,
+            name=name,
+            prefix=_prefix(token),
+            created_at=ts(),
+            revoked_at=None,
+            last_used_at=None,
+        )
+        with self.backend.transaction(write=True) as tx:
+            tx.execute(
+                "INSERT INTO api_keys (id, tenant_id, name, prefix, hash, created_at)"
+                " VALUES (?,?,?,?,?,?)",
+                (
+                    key.id,
+                    key.tenant_id,
+                    key.name,
+                    key.prefix,
+                    self.hasher.hash(token),
+                    key.created_at,
+                ),
+            )
+        return key, token
+
+    def revoke_key(self, key_id: str) -> bool:
+        with self.backend.transaction(write=True) as tx:
+            tx.execute(
+                "UPDATE api_keys SET revoked_at = ? WHERE id = ? AND revoked_at IS NULL",
+                (ts(), key_id),
+            )
+            rows = tx.execute("SELECT revoked_at FROM api_keys WHERE id = ?", (key_id,))
+        with self._lock:
+            self._cache = {k: v for k, v in self._cache.items() if v[0].key_id != key_id}
+        return bool(rows) and rows[0][0] is not None
+
+    def list_keys(self, tenant_id: str) -> list[ApiKey]:
+        with self.backend.transaction() as tx:
+            rows = tx.execute(
+                "SELECT id, tenant_id, name, prefix, created_at, revoked_at, last_used_at"
+                " FROM api_keys WHERE tenant_id = ? ORDER BY created_at",
+                (tenant_id,),
+            )
+        return [
+            ApiKey(
+                id=str(r[0]),
+                tenant_id=str(r[1]),
+                name=str(r[2]),
+                prefix=str(r[3]),
+                created_at=str(r[4]),
+                revoked_at=None if r[5] is None else str(r[5]),
+                last_used_at=None if r[6] is None else str(r[6]),
+            )
+            for r in rows
+        ]
+
+    def authenticate(self, token: str) -> Principal | None:
+        cache_key = hashlib.sha256(token.encode()).hexdigest()
+        with self._lock:
+            hit = self._cache.get(cache_key)
+            if hit is not None and hit[1] > time.monotonic():
+                return hit[0]
+        with self.backend.transaction() as tx:
+            rows = tx.execute(
+                "SELECT id, tenant_id, hash FROM api_keys WHERE prefix = ? AND revoked_at IS NULL",
+                (_prefix(token),),
+            )
+        for key_id, tenant_id, digest in rows:
+            try:
+                self.hasher.verify(str(digest), token)
+            except VerificationError:
+                continue
+            principal = Principal(tenant_id=str(tenant_id), key_id=str(key_id))
+            with self._lock:
+                self._cache[cache_key] = (principal, time.monotonic() + _CACHE_TTL_S)
+            with self.backend.transaction(write=True) as tx:
+                tx.execute("UPDATE api_keys SET last_used_at = ? WHERE id = ?", (ts(), key_id))
+            return principal
+        return None
+
+    # -- bootstrap -------------------------------------------------------------------------
+    def ensure_dev_key(self, token: str) -> Principal:
+        """Development only: make ``token`` a valid key for the local tenant."""
+        existing = self.authenticate(token)
+        if existing is not None:
+            return existing
+        tenant = self.get_tenant(LOCAL_TENANT) or self.create_tenant(
+            "local", tenant_id=LOCAL_TENANT
+        )
+        key, _ = self.create_key(tenant.id, "dev", token=token)
+        return Principal(tenant_id=tenant.id, key_id=key.id)
+
+
+__all__ = ["ApiKey", "AuthService", "Principal", "Tenant", "generate_key"]

hawser_server/cli.py

@@ -0,0 +1,255 @@
+"""``hawserd``: serve, worker, migrate, admin, openapi."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import secrets
+import tempfile
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+from hawser_server import __version__
+from hawser_server.config import ServerConfig
+from hawser_server.services import Services
+
+app = typer.Typer(name="hawserd", help="Hawser control plane.", no_args_is_help=True)
+admin_app = typer.Typer(help="Tenants and API keys.", no_args_is_help=True)
+app.add_typer(admin_app, name="admin")
+console = Console()
+err = Console(stderr=True)
+
+DEV_DIR = Path(".hawserd")
+
+
+def _version(value: bool) -> None:
+    if value:
+        console.print(f"hawserd {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _main(
+    version: Annotated[
+        bool, typer.Option("--version", callback=_version, is_eager=True, help="Show the version.")
+    ] = False,
+) -> None:
+    """Hawser control plane: API, durable worker, migrations."""
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s")
+
+
+def _dev_key() -> str:
+    explicit = os.environ.get("HAWSERD_DEV_API_KEY")
+    if explicit:
+        return explicit
+    DEV_DIR.mkdir(exist_ok=True)
+    path = DEV_DIR / "dev.key"
+    if path.exists():
+        return path.read_text(encoding="utf-8").strip()
+    key = "hk_live_" + secrets.token_urlsafe(30)[:40]
+    path.write_text(key + "\n", encoding="utf-8")
+    path.chmod(0o600)
+    return key
+
+
+def _config(*, dev: bool, **overrides: Any) -> ServerConfig:
+    if dev:
+        overrides.setdefault("dev_api_key", _dev_key())
+    return ServerConfig.load(**overrides)
+
+
+@app.command()
+def serve(  # noqa: PLR0917 - CLI options
+    host: Annotated[str | None, typer.Option("--host")] = None,
+    port: Annotated[int | None, typer.Option("--port")] = None,
+    dev: Annotated[
+        bool, typer.Option("--dev", help="SQLite, local files, in-process worker, dev API key.")
+    ] = False,
+    with_worker: Annotated[
+        bool, typer.Option("--with-worker", help="Run a worker in this process too.")
+    ] = False,
+    migrate: Annotated[
+        bool, typer.Option("--migrate", help="Apply pending migrations before serving.")
+    ] = False,
+    web_dir: Annotated[
+        Path | None, typer.Option("--web-dir", help="Built web app to serve at /app.")
+    ] = None,
+) -> None:
+    """Serve the HTTP API (and the web app at /app when a build is available)."""
+    import uvicorn  # noqa: PLC0415 - heavy import only when serving
+
+    from hawser_server.app import create_app  # noqa: PLC0415
+    from hawser_server.worker import Worker  # noqa: PLC0415
+
+    cfg = _config(dev=dev, host=host, port=port, web_dir=web_dir)
+    svc = Services(cfg, migrate=True if (migrate or dev) else None)
+    who = svc.bootstrap()
+    if dev and who is not None:
+        console.print(
+            f"[bold]dev mode[/]: database {cfg.database_url}, artifacts {cfg.artifacts_dir}\n"
+            f"API key: [bold]{cfg.dev_api_key}[/]  (tenant {who.tenant_id})\n"
+            f"  export HAWSER_SERVER_URL=http://{cfg.host}:{cfg.port} "
+            f"HAWSER_API_KEY={cfg.dev_api_key}"
+        )
+    worker: Worker | None = None
+    if with_worker or dev:
+        worker = Worker(svc)
+        worker.start()
+    try:
+        uvicorn.run(create_app(svc), host=cfg.host, port=cfg.port, log_level="info")
+    finally:
+        if worker is not None:
+            worker.stop(wait=False)
+        svc.close()
+
+
+@app.command()
+def worker(
+    concurrency: Annotated[int | None, typer.Option("--concurrency", "-c")] = None,
+    dev: Annotated[bool, typer.Option("--dev")] = False,
+) -> None:
+    """Run a durable worker (lease runs, execute from checkpoints, deliver webhooks)."""
+    from hawser_server.worker import Worker  # noqa: PLC0415
+
+    cfg = _config(dev=dev)
+    svc = Services(cfg, migrate=True if dev else None)
+    svc.bootstrap()
+    w = Worker(svc, concurrency=concurrency)
+    try:
+        w.run_forever()
+    except KeyboardInterrupt:
+        w.stop()
+    finally:
+        svc.close()
+
+
+@app.command()
+def migrate(
+    status: Annotated[bool, typer.Option("--status", help="Show what is applied.")] = False,
+) -> None:
+    """Apply pending migrations (forward-only)."""
+    from hawser_server.db import open_backend  # noqa: PLC0415
+    from hawser_server.migrations import ALL_MIGRATIONS  # noqa: PLC0415
+
+    cfg = ServerConfig.load()
+    backend = open_backend(cfg.database_url)
+    try:
+        if status:
+            with backend.transaction() as tx:
+                tx.execute(
+                    "CREATE TABLE IF NOT EXISTS schema_migrations"
+                    " (name TEXT PRIMARY KEY, applied_at TEXT NOT NULL)"
+                )
+                done = {
+                    str(r[0]): str(r[1])
+                    for r in tx.execute("SELECT name, applied_at FROM schema_migrations")
+                }
+            for m in ALL_MIGRATIONS:
+                mark = (
+                    f"[green]applied {done[m.name]}[/]" if m.name in done else "[yellow]pending[/]"
+                )
+                console.print(f"{m.name:24} {mark}")
+            return
+        from hawser.storage.schema import apply_migrations  # noqa: PLC0415
+
+        applied = apply_migrations(backend, ALL_MIGRATIONS)
+        console.print(
+            f"applied {len(applied)} migration(s)" + (": " + ", ".join(applied) if applied else "")
+        )
+    finally:
+        backend.close()
+
+
+@admin_app.command("create-tenant")
+def create_tenant(
+    name: Annotated[str, typer.Argument()],
+    tenant_id: Annotated[str | None, typer.Option("--id", help="Explicit ten_... id.")] = None,
+) -> None:
+    """Create a tenant."""
+    svc = Services(ServerConfig.load(), migrate=None)
+    try:
+        t = svc.auth.create_tenant(name, tenant_id=tenant_id)
+        console.print(f"tenant [bold]{t.id}[/] ({t.name})")
+    finally:
+        svc.close()
+
+
+@admin_app.command("list-tenants")
+def list_tenants() -> None:
+    svc = Services(ServerConfig.load(), migrate=None)
+    try:
+        for t in svc.auth.list_tenants():
+            console.print(f"{t.id}  {t.name}  {t.created_at}")
+    finally:
+        svc.close()
+
+
+@admin_app.command("create-key")
+def create_key(
+    tenant: Annotated[str, typer.Option("--tenant", help="Tenant id.")],
+    name: Annotated[str, typer.Option("--name")] = "default",
+) -> None:
+    """Create an API key for a tenant. The key is printed once."""
+    svc = Services(ServerConfig.load(), migrate=None)
+    try:
+        try:
+            key, token = svc.auth.create_key(tenant, name)
+        except KeyError:
+            err.print(f"[red]unknown tenant {tenant}[/]")
+            raise typer.Exit(1) from None
+        console.print(f"key [bold]{key.id}[/] for {tenant}\n{token}")
+    finally:
+        svc.close()
+
+
+@admin_app.command("revoke-key")
+def revoke_key(key_id: Annotated[str, typer.Argument()]) -> None:
+    svc = Services(ServerConfig.load(), migrate=None)
+    try:
+        if svc.auth.revoke_key(key_id):
+            console.print(f"revoked {key_id}")
+        else:
+            err.print(f"[red]unknown key {key_id}[/]")
+            raise typer.Exit(1)
+    finally:
+        svc.close()
+
+
+def openapi_document() -> str:
+    """The OpenAPI document, rendered deterministically."""
+    from hawser_server.app import create_app  # noqa: PLC0415
+
+    cfg = ServerConfig(
+        database_url="sqlite:///:memory:", artifacts_dir=Path(tempfile.mkdtemp(prefix="hawserd-"))
+    )
+    svc = Services(cfg, migrate=True)
+    try:
+        doc = create_app(svc).openapi()
+    finally:
+        svc.close()
+    return json.dumps(doc, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+
+
+@app.command()
+def openapi(
+    out: Annotated[Path, typer.Option("--out")] = Path("api/openapi/openapi.json"),
+    check: Annotated[bool, typer.Option("--check", help="Fail if the file is stale.")] = False,
+) -> None:
+    """Write (or verify) the generated OpenAPI document."""
+    text = openapi_document()
+    if check:
+        if not out.exists() or out.read_text(encoding="utf-8") != text:
+            err.print(f"[red]{out} is stale; run `hawserd openapi`[/]")
+            raise typer.Exit(1)
+        console.print(f"{out} is up to date")
+        return
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(text, encoding="utf-8")
+    console.print(f"wrote {out}")
+
+
+__all__ = ["app", "openapi_document"]

hawser_server/config.py

@@ -0,0 +1,90 @@
+"""Server configuration: ``HAWSERD_*`` environment variables over defaults.
+
+The runtime settings the engine needs (default model, record mode, skill paths, limits) come
+from the regular ``HAWSER_*`` variables through :class:`hawser.config.HawserConfig`.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from hawser.config import HawserConfig
+
+ENV_PREFIX = "HAWSERD_"
+
+
+class ServerConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    #: ``postgresql://user:pass@host:5432/db`` or ``sqlite:///path/to/file.db`` (single node).
+    database_url: str = "sqlite:///./.hawserd/hawserd.db"
+    #: Local artifact directory; ignored when ``s3_bucket`` is set.
+    artifacts_dir: Path = Path("./.hawserd/store")
+    s3_bucket: str | None = None
+    s3_endpoint_url: str | None = None
+    s3_region: str | None = None
+    s3_access_key: str | None = None
+    s3_secret_key: str | None = None
+    s3_presign_ttl_s: int = Field(default=900, ge=1, le=7 * 24 * 3600)
+    #: Serve artifact bytes through the API instead of presigned URLs.
+    artifacts_proxy: bool = True
+
+    host: str = "127.0.0.1"
+    port: int = 8080
+    #: Base URL clients use to reach this server (in webhook payloads and Location headers).
+    public_url: str = "http://127.0.0.1:8080"
+
+    #: Bootstrap one tenant and this API key at start-up. Development and Compose only.
+    dev_api_key: str | None = None
+
+    lease_seconds: int = Field(default=60, ge=5)
+    worker_concurrency: int = Field(default=2, ge=1)
+    worker_max_attempts: int = Field(default=3, ge=1)
+    poll_interval_s: float = Field(default=0.5, gt=0)
+    max_upload_bytes: int = 50 * 1024 * 1024
+
+    webhook_timeout_s: float = 10.0
+    #: Give up on a delivery after this long (dead letter).
+    webhook_max_age_s: int = 24 * 3600
+
+    sse_keepalive_s: float = 15.0
+
+    #: Browser origins allowed to call the API (the Vite dev server by default).
+    cors_origins: list[str] = ["http://localhost:5173", "http://127.0.0.1:5173"]
+    #: Directory with the built web app (``web/dist``); default: the bundled ``static`` folder.
+    web_dir: Path | None = None
+    #: Rendered-page cache entries kept in memory per process.
+    page_cache_entries: int = 64
+
+    #: Engine configuration (``HAWSER_*``).
+    runtime: HawserConfig = Field(default_factory=HawserConfig.load)
+
+    @field_validator("cors_origins", mode="before")
+    @classmethod
+    def _split_origins(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return [o.strip() for o in value.split(",") if o.strip()]
+        return value
+
+    @classmethod
+    def load(cls, **overrides: Any) -> ServerConfig:
+        values: dict[str, Any] = {}
+        for name in cls.model_fields:
+            if name == "runtime":
+                continue
+            env = os.environ.get(f"{ENV_PREFIX}{name.upper()}")
+            if env:  # empty means unset (compose passes blanks through)
+                values[name] = env
+        values.update({k: v for k, v in overrides.items() if v is not None})
+        return cls.model_validate(values)
+
+    @property
+    def is_sqlite(self) -> bool:
+        return self.database_url.startswith("sqlite:")
+
+
+__all__ = ["ENV_PREFIX", "ServerConfig"]