lakana-server 0.12.0__tar.gz

lakana_server-0.12.0/.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.import_linter_cache/
+.coverage
+coverage.json
+mutants/
+htmlcov/
+.DS_Store
+node_modules/
+.idea/
+.vscode/
+.superpowers/
+docs/superpowers/
+graphify-out/
+.worktrees/
+site-build/

lakana_server-0.12.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.5
+Name: lakana-server
+Version: 0.12.0
+Summary: Lakana control plane: REST API, Iceberg REST catalog, worker.
+Project-URL: Homepage, https://github.com/chrschy/lakana
+Project-URL: Documentation, https://github.com/chrschy/lakana/tree/main/docs/site
+Project-URL: Repository, https://github.com/chrschy/lakana
+Project-URL: Issues, https://github.com/chrschy/lakana/issues
+Project-URL: Changelog, https://github.com/chrschy/lakana/blob/main/CHANGELOG.md
+Author: Christopher Schymura
+License-Expression: Apache-2.0
+Keywords: data-platform,duckdb,iceberg,lakehouse
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Requires-Python: >=3.11
+Requires-Dist: fastapi<1,>=0.141
+Requires-Dist: lakana-core==0.12.0
+Requires-Dist: pyarrow>=18.0.0
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+# lakana-server
+
+> **Pre-beta.** Lakana is published as a 0.x pre-beta: the API and the data layout may change
+> between releases, and it is not ready for production data yet. See the
+> [project README](https://github.com/chrschy/lakana#readme).
+
+Lakana control plane: REST API, Iceberg REST catalog, worker.
+
+Part of [Lakana](https://github.com/chrschy/lakana). Installed with `pip install "lakana[server]"`.

lakana_server-0.12.0/README.md

@@ -0,0 +1,9 @@
+# lakana-server
+
+> **Pre-beta.** Lakana is published as a 0.x pre-beta: the API and the data layout may change
+> between releases, and it is not ready for production data yet. See the
+> [project README](https://github.com/chrschy/lakana#readme).
+
+Lakana control plane: REST API, Iceberg REST catalog, worker.
+
+Part of [Lakana](https://github.com/chrschy/lakana). Installed with `pip install "lakana[server]"`.

lakana_server-0.12.0/hatch_build.py

@@ -0,0 +1,39 @@
+"""Hatchling metadata hook: pin `lakana-core` to this exact release.
+
+hatch-vcs resolves every workspace package's version from the same git tag
+(`raw-options.root = "../.."` in each package's `[tool.hatch.version]`), so
+`lakana-core` can be pinned to precisely this build's own version with no
+hand-edited version anywhere (rule 3): hatchling resolves `project.version`
+before any metadata hook's `update()` runs
+(`hatchling.metadata.core.ProjectMetadata.core`), so `metadata["version"]`
+below is already the real, resolved version. See
+`packages/lakana/hatch_build.py`'s `ServerExtraMetadataHook`, which pins
+`lakana-server`/`lakana-worker` inside `lakana`'s `server` extra the same way.
+
+`dependencies` is dynamic in `pyproject.toml`, so hatchling requires this
+hook to supply the *entire* list, not just the pinned addition. The other
+dependencies, with their explanatory comments, live under this hook's own
+config table (`[tool.hatch.metadata.hooks.custom]`) so they stay readable as
+ordinary TOML instead of being hard-coded here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+
+
+class CoreDependencyMetadataHook(MetadataHookInterface):
+    """Appends a `lakana-core==<version>` pin to the configured dependencies."""
+
+    def update(self, metadata: dict[str, Any]) -> None:
+        """Set `dependencies` to the configured list plus a `lakana-core` pin.
+
+        Parameters
+        ----------
+        metadata
+            The `project` table, mutated in place.
+        """
+        version = metadata["version"]
+        metadata["dependencies"] = [*self.config["dependencies"], f"lakana-core=={version}"]

lakana_server-0.12.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lakana-server"
+description = "Lakana control plane: REST API, Iceberg REST catalog, worker."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "Christopher Schymura" }]
+keywords = ["lakehouse", "duckdb", "iceberg", "data-platform"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "License :: OSI Approved :: Apache Software License",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+]
+urls = { Homepage = "https://github.com/chrschy/lakana", Documentation = "https://github.com/chrschy/lakana/tree/main/docs/site", Repository = "https://github.com/chrschy/lakana", Issues = "https://github.com/chrschy/lakana/issues", Changelog = "https://github.com/chrschy/lakana/blob/main/CHANGELOG.md" }
+dynamic = ["version", "dependencies"]
+
+[project.scripts]
+lakana-server = "lakana_server.__main__:main"
+
+[dependency-groups]
+# The workspace `lakana` SDK, for the SDK contract test
+# (tests/sdk/test_sdk_contract.py) and the SDK end-to-end tests
+# (tests/sdk/), which drive the app only through `lakana.Client` -- never
+# imported by lakana_server itself (see server-goes-through-core and
+# sdk-is-independent in .importlinter; this is a dev-only, test-time
+# dependency, unrelated to either contract).
+dev = ["lakana"]
+
+[tool.uv.sources]
+lakana-core = { workspace = true }
+lakana = { workspace = true }
+
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "../.." }
+
+[tool.hatch.metadata.hooks.custom]
+# Loads `hatch_build.py`'s `CoreDependencyMetadataHook`, which appends
+# `lakana-core==<this build's version>` to the `dependencies` list below,
+# pinning lakana-server to exactly this release's lakana-core -- the
+# same hatch-vcs-resolved version pattern as `packages/lakana/hatch_build.py`'s
+# `ServerExtraMetadataHook`. `dependencies` lives here, not under
+# `[project]`, because hatchling requires the hook to supply the *entire*
+# list once `dependencies` is dynamic; keeping the other pins and their
+# comments in this table (rather than hard-coding them into hatch_build.py)
+# keeps them visible and editable as ordinary TOML.
+dependencies = [
+    "fastapi>=0.141,<1",
+    # Decodes a caller-submitted Arrow IPC stream for the governed append
+    # route (lakana_server.api.platform.tables.append_table_data). Already
+    # arrives transitively through lakana-core's own pyiceberg/pyarrow
+    # dependency, but this package imports it directly now, so it is
+    # declared directly too rather than relying on another package's
+    # transitive dependency graph. Apache-2.0, same as lakana-core's own copy.
+    "pyarrow>=18.0.0",
+    # ASGI server for the `lakana-server` console script. BSD-3-Clause.
+    "uvicorn>=0.30",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lakana_server"]

lakana_server-0.12.0/src/lakana_server/__init__.py

@@ -0,0 +1 @@
+"""Lakana control plane: REST API, Iceberg REST catalog, worker."""

lakana_server-0.12.0/src/lakana_server/__main__.py

@@ -0,0 +1,56 @@
+"""Entry point for the `lakana-server` console script.
+
+`lakana-server` serves the API with uvicorn; `lakana-server migrate` applies the
+metadata database migrations and exits. Both read `LAKANA_*` settings.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+import uvicorn
+
+from lakana_core import migrate
+from lakana_core.log_setup import configure_logging
+from lakana_server.app import create_app
+from lakana_server.log_config import uvicorn_log_config
+from lakana_server.settings import Settings
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Serve the API, or run a subcommand.
+
+    Parameters
+    ----------
+    argv
+        Command-line arguments without the program name; `sys.argv[1:]` when
+        `None`.
+
+    Notes
+    -----
+    Logging is set up once the settings are read (`lakana_core.log_setup.configure_logging`):
+    `LAKANA_LOG__LEVEL` (INFO by default) and above to stderr with time, level and logger
+    name, like the worker, so the INFO lines of `lakana_*` loggers reach
+    `docker compose logs server`. Uvicorn keeps its own handlers, with formatters that escape
+    control characters like the root handler's (`lakana_server.log_config`), and gets the same
+    level, so its access log (one line per request) is printed at INFO and DEBUG only.
+    """
+    parser = argparse.ArgumentParser(prog="lakana-server", description="Run the Lakana API server.")
+    parser.add_argument("command", nargs="?", choices=["migrate"], help="migrate: apply migrations")
+    args = parser.parse_args(argv)
+    settings = Settings()
+    configure_logging(settings.log.level)
+    if args.command == "migrate":
+        migrate.upgrade(settings.database.url)
+        return
+    uvicorn.run(
+        create_app(settings),
+        host=settings.host,
+        port=settings.port,
+        log_level=settings.log.level.lower(),
+        log_config=uvicorn_log_config(),
+    )
+
+
+if __name__ == "__main__":  # pragma: no cover — exercised only by `python -m lakana_server`
+    main()

lakana_server-0.12.0/src/lakana_server/api/__init__.py

@@ -0,0 +1 @@
+"""The control plane's HTTP surface: the platform API and the Iceberg REST catalog."""

lakana_server-0.12.0/src/lakana_server/api/iceberg/__init__.py

@@ -0,0 +1 @@
+"""The Iceberg REST Catalog API: config, namespaces, and tables."""

lakana_server-0.12.0/src/lakana_server/api/iceberg/encoding.py

@@ -0,0 +1,60 @@
+r"""Conversion between the Iceberg REST wire format and NamespacePath.
+
+Two wire shapes exist for the same value: a URL path segment joins parts
+with the raw unit separator character (`\x1f`), matching
+`lakana_core.identifiers.NAMESPACE_SEPARATOR` exactly — this is not a
+coincidence; the separator was chosen for this reason (see the architecture
+doc's identity decisions). FastAPI/Starlette URL-decodes path parameters
+before an endpoint ever sees them, so a namespace segment arrives here
+already containing the literal separator character, not a percent-encoded
+stand-in for it. A JSON response body instead uses a list of parts.
+`decode_namespace` and `encode_namespace` are not a round-trip pair of each
+other: `decode_namespace` only ever parses the joined URL-segment form, and
+`encode_namespace` only ever produces the list form used in response
+bodies — no call site passes one function's output into the other.
+"""
+
+from __future__ import annotations
+
+from lakana_core.identifiers import NamespacePath
+
+
+def decode_namespace(raw: str) -> NamespacePath:
+    """Parse a namespace path segment from a request URL.
+
+    Parameters
+    ----------
+    raw
+        The `{namespace}` path parameter, already URL-decoded by Starlette,
+        so it already contains the literal separator character rather than
+        a percent-encoded stand-in for it.
+
+    Returns
+    -------
+    NamespacePath
+        The parsed path.
+
+    Raises
+    ------
+    lakana_core.errors.ValidationError
+        If any component is invalid.
+    """
+    return NamespacePath.parse(raw)
+
+
+def encode_namespace(path: NamespacePath) -> list[str]:
+    """Render a namespace as the Iceberg wire format's list of parts.
+
+    Parameters
+    ----------
+    path
+        The namespace to render.
+
+    Returns
+    -------
+    list of str
+        The namespace's parts, outermost first — the shape used in every
+        JSON response that names a namespace (`ListNamespacesResponse`,
+        `NamespaceResponse`, `ListTablesResponse`'s per-entry `namespace`).
+    """
+    return list(path.parts)

lakana_server-0.12.0/src/lakana_server/api/iceberg/route.py

@@ -0,0 +1,203 @@
+"""The error-shaping route class for the Iceberg REST router.
+
+FastAPI's exception handlers are registered on the application as a whole,
+but the Iceberg REST specification mandates a response body
+(`{"error": {"message", "type", "code"}}`) different from the platform API's.
+This route class wraps each endpoint's dependency resolution and handler
+call, catching the same exception vocabulary and reshaping it before it
+would ever reach the app-level handlers `install_exception_handlers` sets up
+— those serve the platform API only.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+import pydantic
+from fastapi import Request, Response
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException
+
+from lakana_core.errors import (
+    AlreadyExistsError,
+    AuthenticationError,
+    ConflictError,
+    KeptAfterCheckError,
+    LakanaError,
+    NotFoundError,
+    NotPublishedError,
+    PermissionDenied,
+    ValidationError,
+)
+from lakana_server.api.routing import AuthenticateFirstRoute
+
+logger = logging.getLogger(__name__)
+"""Logger for exceptions outside the caught vocabulary.
+
+The terminal `except Exception` branch reshapes an unmodeled exception into
+an opaque client response and must not let it propagate further, so this is
+the only remaining way its traceback reaches the server side to be
+correlated with the client-visible `type` (see `_OPAQUE_MESSAGE`).
+"""
+
+
+_STATUS_CODES: dict[type[Exception], int] = {
+    AuthenticationError: 401,
+    NotFoundError: 404,
+    NotPublishedError: 404,
+    KeptAfterCheckError: 404,
+    AlreadyExistsError: 409,
+    ConflictError: 409,
+    ValidationError: 422,
+    PermissionDenied: 403,
+    pydantic.ValidationError: 422,
+    RequestValidationError: 422,
+}
+"""Maps each caught exception type to its HTTP status code.
+
+`NotPublishedError` is a 404 here, not the 409 of the platform API: an engine reads the
+Iceberg REST catalog's 404 as "no such table", which is what a table with no published
+snapshot is to it, and the message says why. `KeptAfterCheckError` (a task refused a table
+that was kept after a failed check) is a 404 for the same reason: to the task's engine
+the table is not there to read. The lookup is by exact type, so a subclass of
+a mapped error needs its own entry.
+
+`pydantic.ValidationError` is listed explicitly and is distinct from
+`lakana_core.errors.ValidationError`, which is also in this table under its
+own name — two different classes named `ValidationError` (a third,
+`pyiceberg.exceptions.ValidationError`, is unrelated and not caught here).
+`RequestValidationError` is a fourth, separate class: FastAPI raises it when
+a request body fails to parse against its Pydantic model, before an
+endpoint's own body ever runs — distinct from a `pydantic.ValidationError`
+raised inside a handler doing its own parsing (for example `iceberg_json`).
+"""
+
+
+_OPAQUE_MESSAGE = "Internal server error"
+"""Stands in for the message of an exception outside the caught vocabulary.
+
+An error Lakana did not model is by definition one whose text was never
+written for an external reader: it may name an internal path, a SQL
+fragment, or a third-party library's internals. The exception's class name
+is still reported in `type`, which is enough to correlate a client-side
+report with the server-side traceback without spilling the message itself.
+"""
+
+
+def _error_response(exc: Exception, status_code: int, message: str) -> JSONResponse:
+    """Build the Iceberg REST specification's error body.
+
+    Parameters
+    ----------
+    exc
+        The caught exception, whose class name becomes the body's `type`.
+    status_code
+        The HTTP status to answer with, echoed into the body's `code` as
+        the specification requires.
+    message
+        The human-readable message for the body.
+
+    Returns
+    -------
+    JSONResponse
+        A response carrying `{"error": {"message", "type", "code"}}`.
+    """
+    return JSONResponse(
+        status_code=status_code,
+        content={"error": {"message": message, "type": type(exc).__name__, "code": status_code}},
+    )
+
+
+def _error_message(exc: Exception) -> str:
+    """Render a caught exception's message for the Iceberg error body.
+
+    Parameters
+    ----------
+    exc
+        The caught exception.
+
+    Returns
+    -------
+    str
+        For a `RequestValidationError`, each error's dotted location and
+        message joined together — `str(exc)` on this class defaults to a
+        vague ``"N validation errors for Request"`` with no detail on what
+        was actually wrong. For every other caught exception, `str(exc)`.
+    """
+    if isinstance(exc, RequestValidationError):
+        return "; ".join(
+            f"{'.'.join(str(part) for part in error['loc'])}: {error['msg']}"
+            for error in exc.errors()
+        )
+    return str(exc)
+
+
+class IcebergRoute(AuthenticateFirstRoute):
+    """An APIRoute that reshapes errors into the Iceberg REST error body.
+
+    Used as `route_class` for the Iceberg router only (`router.py`). The
+    platform API keeps FastAPI's default route class and relies on
+    `install_exception_handlers` instead.
+    """
+
+    def get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]:
+        """Wrap the original handler with Iceberg-shaped error handling.
+
+        Returns
+        -------
+        Callable
+            A handler that catches `LakanaError`, `pydantic.ValidationError`,
+            and `RequestValidationError` — raised either inside a dependency
+            or inside the endpoint body, since both run inside the call this
+            wraps — and returns the spec-mandated JSON shape instead of
+            letting them propagate to FastAPI's default handling. A
+            `starlette.exceptions.HTTPException` raised by FastAPI's own
+            request-handling machinery (for example an invalid-UTF-8 body)
+            is reshaped into the same JSON body but keeps its own
+            `status_code` and `detail` rather than being folded into the
+            terminal 500 — it is a genuine client error, not an unmodeled
+            one. A terminal `except Exception` catches everything else as a
+            500 in the same shape, which is what the design's mapping
+            table means by its last row, "uncaught `LakanaError` / anything
+            else". Without it a stray `KeyError` or third-party exception
+            reaches Starlette's default handler and the client gets a
+            plain-text body on the one surface whose error shape is
+            externally specified. That branch also logs the exception,
+            traceback included, via `logger.exception` before responding —
+            otherwise nothing outside this process would ever record that
+            an unmodeled error happened, and `_OPAQUE_MESSAGE`'s promise
+            that the client-visible `type` can be correlated with a
+            server-side traceback would have no traceback to correlate
+            with. `KeyboardInterrupt` and `SystemExit` derive from
+            `BaseException`, not `Exception`, and so still propagate.
+        """
+        original_route_handler = super().get_route_handler()
+
+        async def custom_route_handler(request: Request) -> Response:
+            """Call the original handler, reshaping any caught error.
+
+            Parameters
+            ----------
+            request
+                The incoming request.
+
+            Returns
+            -------
+            Response
+                The original response on success, or a spec-shaped
+                `JSONResponse` on a caught error.
+            """
+            try:
+                return await original_route_handler(request)
+            except (LakanaError, pydantic.ValidationError, RequestValidationError) as exc:
+                return _error_response(exc, _STATUS_CODES.get(type(exc), 500), _error_message(exc))
+            except HTTPException as exc:
+                return _error_response(exc, exc.status_code, str(exc.detail))
+            except Exception as exc:
+                logger.exception("Unhandled exception in Iceberg REST route: %s", exc)
+                return _error_response(exc, 500, _OPAQUE_MESSAGE)
+
+        return custom_route_handler