tangram-core 0.2.0__cp313-cp313-win_amd64.whl

tangram_core/backend.py

@@ -0,0 +1,335 @@
+from __future__ import annotations
+
+import asyncio
+import importlib.resources
+import json
+import logging
+import re
+from contextlib import AsyncExitStack, asynccontextmanager
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from functools import partial
+from importlib.metadata import Distribution, PackageNotFoundError
+from importlib.resources.abc import Traversable
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    AsyncGenerator,
+    Awaitable,
+    Callable,
+    Iterable,
+    TypeAlias,
+)
+
+import httpx
+import redis.asyncio as redis
+import uvicorn
+from fastapi import Depends, FastAPI, Request
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from platformdirs import user_cache_dir
+
+from .config import CacheEntry, Config, FrontendChannelConfig, FrontendConfig
+from .plugin import load_plugin, scan_plugins
+
+if TYPE_CHECKING:
+    from .plugin import DistName, Plugin
+
+logger = logging.getLogger(__name__)
+
+
+# see https://www.starlette.io/lifespan/#lifespan-state
+@dataclass
+class BackendState:
+    redis_client: redis.Redis
+    http_client: httpx.AsyncClient
+    config: Config
+
+
+async def get_state(request: Request) -> BackendState:
+    return request.app.state.backend_state  # type: ignore
+
+
+InjectBackendState: TypeAlias = Annotated[BackendState, Depends(get_state)]
+
+
+def resolve_frontend(*, path: str, dist_name: str) -> Path | Traversable | None:
+    # always try to parse from direct url first (this is robust for editable
+    # installs like `uv sync --all-packages`)
+    try:
+        dist = Distribution.from_name(dist_name)
+        if direct_url_content := dist.read_text("direct_url.json"):
+            direct_url_data = json.loads(direct_url_content)
+            if (url := direct_url_data.get("url")) and (
+                path1 := Path(url.removeprefix("file://")) / path
+            ).is_dir():
+                return path1
+    except (PackageNotFoundError, json.JSONDecodeError, FileNotFoundError):
+        pass
+
+    # fallback in case it was installed via pip
+    if (path2 := importlib.resources.files(dist_name) / path).is_dir():
+        return path2
+    return None
+
+
+def load_enabled_plugins(
+    config: Config,
+) -> list[tuple[DistName, Plugin]]:
+    loaded_plugins = []
+    enabled_plugin_names = set(config.core.plugins)
+
+    for entry_point in scan_plugins():
+        if entry_point.name not in enabled_plugin_names:
+            continue
+        if (plugin := load_plugin(entry_point)) is not None:
+            loaded_plugins.append(plugin)
+
+    return loaded_plugins
+
+
+@asynccontextmanager
+async def lifespan(
+    app: FastAPI, backend_state: BackendState
+) -> AsyncGenerator[None, None]:
+    # we don't need to __aenter__ httpx.AsyncClient again
+    async with backend_state.redis_client:
+        app.state.backend_state = backend_state
+        yield
+
+
+def make_cache_route_handler(
+    entry: CacheEntry, state: BackendState
+) -> Callable[..., Awaitable[FileResponse]]:
+    """
+    Factory function that creates a route handler for caching and serving files.
+    Dynamically handles URL parameters found in both serve_route and origin.
+
+    Args:
+        entry: Cache entry configuration
+        state: Backend state with http_client for fetching remote resources
+
+    Returns:
+        Async function that handles the route with dynamic parameters
+    """
+    from inspect import Parameter, Signature
+
+    # Extract parameter names from the serve_route (e.g., {fontstack}, {range})
+    param_pattern = re.compile(r"\{(\w+)\}")
+    params = param_pattern.findall(entry.serve_route)
+
+    async def cache_route_handler(**kwargs: str) -> FileResponse:
+        local_path = entry.local_path
+        if local_path is None:
+            local_path = Path(user_cache_dir("tangram_core"))
+            if not local_path.exists():
+                local_path.mkdir(parents=True)
+        else:
+            local_path = local_path.expanduser()
+
+        # Build the local file path by replacing parameters
+        local_file = local_path
+        for param in params:
+            if param in kwargs:
+                local_file = local_file / kwargs[param]
+
+        logger.info(f"Serving cached file from {local_file}")
+
+        if not local_file.exists():
+            assert entry.origin is not None
+            # Build the remote URL by replacing parameters
+            remote_url = entry.origin
+            for param, value in kwargs.items():
+                remote_url = remote_url.replace(f"{{{param}}}", value)
+
+            logger.info(f"Downloading from {remote_url} to {local_file}")
+            c = await state.http_client.get(remote_url)
+            c.raise_for_status()
+            local_file.parent.mkdir(parents=True, exist_ok=True)
+            local_file.write_bytes(c.content)
+
+        return FileResponse(path=local_file, media_type=entry.media_type)
+
+    # Create explicit parameters for the function signature
+    sig_params = [
+        Parameter(
+            name=param,
+            kind=Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=str,
+        )
+        for param in params
+    ]
+    cache_route_handler.__signature__ = Signature(  # type: ignore
+        parameters=sig_params,
+        return_annotation=FileResponse,
+    )
+
+    return cache_route_handler
+
+
+def create_app(
+    backend_state: BackendState,
+    loaded_plugins: Iterable[tuple[DistName, Plugin]],
+) -> FastAPI:
+    app = FastAPI(lifespan=partial(lifespan, backend_state=backend_state))
+    frontend_plugins = []
+
+    for dist_name, plugin in loaded_plugins:
+        for router in plugin.routers:
+            app.include_router(router)
+
+        if (p := plugin.frontend_path) is not None and (
+            frontend_path_resolved := resolve_frontend(path=p, dist_name=dist_name)
+        ) is not None:
+            app.mount(
+                f"/plugins/{dist_name}",
+                StaticFiles(directory=str(frontend_path_resolved)),
+                name=dist_name,
+            )
+            frontend_plugins.append(dist_name)
+
+    # unlike v0.1 which uses `process.env`, v0.2 *compiles* the js so we no
+    # no longer have access to it, so we selectively forward the config.
+    @app.get("/config")
+    async def get_frontend_config(
+        state: Annotated[BackendState, Depends(get_state)],
+    ) -> FrontendConfig:
+        channel_cfg = state.config.channel
+        if channel_cfg.public_url:
+            channel_url = channel_cfg.public_url
+        else:
+            # for local/non-proxied setups, user must set a reachable host.
+            # '0.0.0.0' is for listening, not connecting.
+            host = "localhost" if channel_cfg.host == "0.0.0.0" else channel_cfg.host
+            channel_url = f"http://{host}:{channel_cfg.port}"
+
+        return FrontendConfig(
+            channel=FrontendChannelConfig(url=channel_url),
+            map=state.config.map,
+        )
+
+    @app.get("/manifest.json")
+    async def get_manifest() -> JSONResponse:
+        return JSONResponse(content={"plugins": frontend_plugins})
+
+    # Cache mechanism - MUST be registered BEFORE the catch-all frontend mount
+    for cache_entry in backend_state.config.cache.entries:
+        logger.info(
+            f"caching {cache_entry.origin} to {cache_entry.local_path} "
+            f"and serving at {cache_entry.serve_route}"
+        )
+        route_handler = make_cache_route_handler(cache_entry, backend_state)
+
+        logger.info(
+            f"Registering route: GET {cache_entry.serve_route} with dynamic params"
+        )
+        app.add_api_route(
+            cache_entry.serve_route,
+            route_handler,
+            methods=["GET"],
+            name=f"cache-{cache_entry.serve_route.replace('/', '_')}",
+        )
+
+    # Frontend mount - this is a catch-all and must come LAST
+    if (
+        frontend_path := resolve_frontend(
+            path="dist-frontend", dist_name="tangram_core"
+        )
+    ) is None:
+        raise ValueError(
+            "error: frontend was not found, did you run `pnpm i && pnpm run build`?"
+        )
+    app.mount("/", StaticFiles(directory=str(frontend_path), html=True), name="core")
+
+    return app
+
+
+LOG_LEVEL_MAP = {
+    "TRACE": logging.DEBUG,
+    "DEBUG": logging.DEBUG,
+    "INFO": logging.INFO,
+    "WARN": logging.WARNING,
+    "ERROR": logging.ERROR,
+}
+
+
+async def run_channel_service(config: Config) -> None:
+    from . import _core
+
+    _core.init_tracing_stderr(config.core.log_level)
+
+    rust_config = _core.ChannelConfig(
+        host=config.channel.host,
+        port=config.channel.port,
+        redis_url=config.core.redis_url,
+        jwt_secret=config.channel.jwt_secret,
+        jwt_expiration_secs=config.channel.jwt_expiration_secs,
+        id_length=config.channel.id_length,
+    )
+    await _core.run(rust_config)
+
+
+async def run_services(
+    backend_state: BackendState,
+    loaded_plugins: Iterable[tuple[DistName, Plugin]],
+) -> AsyncGenerator[asyncio.Task[None], None]:
+    yield asyncio.create_task(run_channel_service(backend_state.config))
+
+    for dist_name, plugin in loaded_plugins:
+        for _, service_func in sorted(
+            plugin.services, key=lambda s: (s[0], s[1].__name__)
+        ):
+            yield asyncio.create_task(service_func(backend_state))
+            logger.info(f"started service from plugin: {dist_name}")
+
+
+async def run_server(
+    backend_state: BackendState, loaded_plugins: list[tuple[DistName, Plugin]]
+) -> None:
+    app_instance = create_app(backend_state, loaded_plugins)
+    server_config = uvicorn.Config(
+        app_instance,
+        host=backend_state.config.server.host,
+        port=backend_state.config.server.port,
+        log_config=get_log_config_dict(backend_state.config),
+    )
+    server = uvicorn.Server(server_config)
+    await server.serve()
+
+
+async def start_tasks(config: Config) -> None:
+    loaded_plugins = load_enabled_plugins(config)
+
+    async with AsyncExitStack() as stack:
+        redis_client = await stack.enter_async_context(
+            redis.from_url(config.core.redis_url)  # type: ignore
+        )
+        http_client = await stack.enter_async_context(httpx.AsyncClient(http2=True))
+        state = BackendState(
+            redis_client=redis_client, http_client=http_client, config=config
+        )
+
+        server_task = asyncio.create_task(run_server(state, loaded_plugins))
+        service_tasks = [s async for s in run_services(state, loaded_plugins)]
+
+        await asyncio.gather(server_task, *service_tasks)
+
+
+def get_log_config_dict(config: Config) -> dict[str, Any]:
+    def format_time(dt: datetime) -> str:
+        return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ ")
+
+    return {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "handlers": {
+            "default": {
+                "class": "rich.logging.RichHandler",
+                "log_time_format": format_time,
+                "omit_repeated_times": False,
+            },
+        },
+        "root": {"handlers": ["default"], "level": config.core.log_level.upper()},
+    }

tangram_core/colour.ts

@@ -0,0 +1,71 @@
+// adapted from: https://github.com/color-js/color.js/blob/main/src/spaces/oklch.js
+type Vector3 = [number, number, number];
+
+const multiplyMatrices = (A: number[], B: Vector3): Vector3 => {
+  return [
+    A[0] * B[0] + A[1] * B[1] + A[2] * B[2],
+    A[3] * B[0] + A[4] * B[1] + A[5] * B[2],
+    A[6] * B[0] + A[7] * B[1] + A[8] * B[2]
+  ];
+};
+
+const oklch2oklab = ([l, c, h]: Vector3): Vector3 => [
+  l,
+  isNaN(h) ? 0 : c * Math.cos((h * Math.PI) / 180),
+  isNaN(h) ? 0 : c * Math.sin((h * Math.PI) / 180)
+];
+
+const srgbLinear2rgb = (rgb: Vector3): Vector3 =>
+  rgb.map(c =>
+    Math.abs(c) > 0.0031308
+      ? (c < 0 ? -1 : 1) * (1.055 * Math.pow(Math.abs(c), 1 / 2.4) - 0.055)
+      : 12.92 * c
+  ) as Vector3;
+
+const oklab2xyz = (lab: Vector3): Vector3 => {
+  const LMSg = multiplyMatrices(
+    [
+      1, 0.3963377773761749, 0.2158037573099136, 1, -0.1055613458156586,
+      -0.0638541728258133, 1, -0.0894841775298119, -1.2914855480194092
+    ],
+    lab
+  );
+  const LMS = LMSg.map(val => val ** 3) as Vector3;
+  return multiplyMatrices(
+    [
+      1.2268798758459243, -0.5578149944602171, 0.2813910456659647, -0.0405757452148008,
+      1.112286803280317, -0.0717110580655164, -0.0763729366746601, -0.4214933324022432,
+      1.5869240198367816
+    ],
+    LMS
+  );
+};
+
+const xyz2rgbLinear = (xyz: Vector3): Vector3 => {
+  return multiplyMatrices(
+    [
+      3.2409699419045226, -1.537383177570094, -0.4986107602930034, -0.9692436362808796,
+      1.8759675015077202, 0.04155505740717559, 0.05563007969699366,
+      -0.20397695888897652, 1.0569715142428786
+    ],
+    xyz
+  );
+};
+
+export const oklch2rgb = (lch: Vector3): Vector3 =>
+  srgbLinear2rgb(xyz2rgbLinear(oklab2xyz(oklch2oklab(lch))));
+
+export function oklchToDeckGLColor(
+  l: number,
+  c: number,
+  h: number,
+  a: number = 255
+): [number, number, number, number] {
+  const rgb = oklch2rgb([l, c, h]);
+  return [
+    Math.max(0, Math.min(255, Math.round(rgb[0] * 255))),
+    Math.max(0, Math.min(255, Math.round(rgb[1] * 255))),
+    Math.max(0, Math.min(255, Math.round(rgb[2] * 255))),
+    a
+  ];
+}

tangram_core/config.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+
+@dataclass
+class ServerConfig:
+    host: str = "127.0.0.1"
+    port: int = 2346
+
+
+@dataclass
+class ChannelConfig:
+    # TODO: we should make it clear that host:port is for the *backend* to
+    # listen on, and not to be confused with the frontend.
+    host: str = "127.0.0.1"
+    port: int = 2347
+    public_url: str | None = None
+    jwt_secret: str = "secret"
+    jwt_expiration_secs: int = 315360000  # 10 years
+    id_length: int = 8
+
+
+@dataclass
+class UrlConfig:
+    url: str
+    type: str = "vector"
+
+
+@dataclass
+class SourceSpecification:
+    carto: UrlConfig | None = None
+    protomaps: UrlConfig | None = None
+
+
+@dataclass
+class StyleSpecification:
+    sources: SourceSpecification | None = None
+    glyphs: str = "https://cdn.protomaps.com/fonts/pbf/{fontstack}/{range}.pbf"
+    layers: list[Any] | None = None
+    version: Literal[8] = 8
+
+
+@dataclass
+class MapConfig:
+    style: str | StyleSpecification = (
+        "https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json"
+    )
+    attribution: str = (
+        '&copy; <a href="https://www.openstreetmap.org/copyright">'
+        "OpenStreetMap</a> contributors &copy; "
+        '<a href="https://carto.com/attributions">CARTO</a>'
+    )
+    center_lat: float = 48.0
+    center_lon: float = 7.0
+    zoom: int = 4
+    pitch: float = 0
+    bearing: float = 0
+    lang: str = "en"
+
+
+@dataclass
+class CoreConfig:
+    redis_url: str = "redis://127.0.0.1:6379"
+    plugins: list[str] = field(default_factory=list)
+    log_level: str = "INFO"
+
+
+@dataclass
+class CacheEntry:
+    # origin url (if None, just serve the local file)
+    origin: str | None = None
+    # local path to cache the file
+    local_path: Path | None = None
+    # how to serve the file
+    serve_route: str = ""
+    # media type for the served file
+    media_type: str = "application/octet-stream"
+
+
+@dataclass
+class CacheConfig:
+    entries: list[CacheEntry] = field(default_factory=list)
+
+
+@dataclass
+class Config:
+    core: CoreConfig = field(default_factory=CoreConfig)
+    server: ServerConfig = field(default_factory=ServerConfig)
+    channel: ChannelConfig = field(default_factory=ChannelConfig)
+    map: MapConfig = field(default_factory=MapConfig)
+    plugins: dict[str, Any] = field(default_factory=dict)
+    cache: CacheConfig = field(default_factory=CacheConfig)
+
+    @classmethod
+    def from_file(cls, config_path: Path) -> Config:
+        if sys.version_info < (3, 11):
+            import tomli as tomllib
+        else:
+            import tomllib
+        from pydantic import TypeAdapter
+
+        with open(config_path, "rb") as f:
+            cfg_data = tomllib.load(f)
+
+        config_adapter = TypeAdapter(cls)
+        config = config_adapter.validate_python(cfg_data)
+        return config
+
+
+@dataclass
+class FrontendChannelConfig:
+    url: str
+
+
+@dataclass
+class FrontendConfig:
+    channel: FrontendChannelConfig
+    map: MapConfig