Add input validation, Node.js support, and Docker test environment

- Add input validation for Map parameters (zoom, pitch, bearing, center, dimensions)
- Add Node.js runtime support alongside Bun for maplibre-gl-native compatibility
- Update Dockerfile.test for integration tests with Xvfb headless rendering
- Add 15 validation unit tests (TestValidation class)
- Fix vendor binary detection with ldd system library checks
- Update URLs and version to 0.1.0-alpha
- Improve error messages with actionable guidance

Author: adonm

Dockerfile.test

@@ -1,55 +1,59 @@
 # Dockerfile for running mlnative tests with proper library versions
+# Provides libjpeg8 and libicu74 needed by maplibre-gl-native
+# Uses Node.js because maplibre-gl-native is a V8 native addon
 FROM ubuntu:24.04
 
-# Install dependencies
-RUN apt-get update && apt-get install -y \
+# Install minimal dependencies + xvfb for headless rendering
+RUN apt-get update && apt-get install -y --no-install-recommends \
     curl \
-    build-essential \
+    ca-certificates \
     libjpeg8 \
     libicu74 \
     libgl1 \
     libglx0 \
     libopengl0 \
+    libcurl4 \
+    libuv1 \
+    libx11-6 \
+    libxext6 \
+    libwebp7 \
+    libpng16-16t64 \
     python3.12 \
     python3.12-venv \
-    python3-pip \
+    unzip \
+    xvfb \
     && rm -rf /var/lib/apt/lists/*
 
-# Install mise (tool manager)
-RUN curl https://mise.run | sh
-ENV PATH="/root/.local/bin:$PATH"
-
-# Trust mise config and install tools
-RUN mise trust
-RUN mise install
-
 # Set working directory
 WORKDIR /app
 
-# Copy config files first (for tool installation)
-COPY mise.toml ./
+# Install mise and tools (includes node for native module compatibility)
+RUN curl https://mise.run | sh
+ENV PATH="/root/.local/bin:$PATH"
 
-# Trust and install tools
-RUN mise trust
-RUN mise install
+# Create mise config with Node 22 (ABI 127 has prebuilt maplibre binaries)
+RUN echo '[tools]\nuv = "latest"\njust = "latest"\nnode = "22"' > /app/mise.toml
+RUN mise trust && mise install
 
-# Copy remaining project files
+# Copy project files
 COPY pyproject.toml Justfile README.md ./
 COPY mlnative/ ./mlnative/
 COPY examples/ ./examples/
 COPY tests/ ./tests/
 COPY scripts/ ./scripts/
 
-# Setup project using mise exec
-RUN mise exec -- just setup
-
-# Build vendor binaries
-RUN mise exec -- just build-vendor
-
-# Install native module
-RUN cd mlnative/_vendor/linux-x64 && \
-    mise exec -- bun install @maplibre/maplibre-gl-native && \
-    mise exec -- bun pm untrusted
-
-# Run tests
-CMD ["mise", "exec", "--", "just", "test"]
+# Setup Python environment  
+RUN mise exec -- uv venv && mise exec -- uv pip install -e ".[dev,web]"
+
+# Install native module using npm with explicit postinstall
+RUN PLATFORM=$(uname -m | sed 's/x86_64/x64/' | sed 's/aarch64/arm64/') && \
+    VENDOR_DIR="mlnative/_vendor/linux-${PLATFORM}" && \
+    rm -rf "${VENDOR_DIR}/node_modules" "${VENDOR_DIR}/package-lock.json" && \
+    mkdir -p "${VENDOR_DIR}" && \
+    cd "${VENDOR_DIR}" && \
+    echo '{"dependencies": {"@maplibre/maplibre-gl-native": "^6.3.0"}}' > package.json && \
+    mise exec -- npm cache clean --force && \
+    mise exec -- npm install --prefer-online
+
+# Run tests with Xvfb virtual display
+CMD ["sh", "-c", "Xvfb :99 -screen 0 1024x768x24 & export DISPLAY=:99 && sleep 1 && mise exec -- just test"]

Justfile

@@ -28,7 +28,7 @@ test-filter PATTERN:
 
 # Run only unit tests (skip integration tests that need vendor binaries)
 test-unit:
-    uv run python -m pytest tests/ -v -k "not render" --tb=short
+    uv run python -m pytest tests/ -v -k "Validation" --tb=short
 
 # Run linting
 lint:
@@ -111,8 +111,8 @@ stats:
 
 # Run tests in container (for systems with incompatible libraries)
 test-docker:
-    podman build -f Dockerfile.test -t mlnative-test .
-    podman run --rm mlnative-test
+    docker build -f Dockerfile.test -t mlnative-test .
+    docker run --rm mlnative-test
 
 # Install all tools via mise (local dev)
 install-tools:

mlnative/__init__.py

@@ -7,5 +7,5 @@
 from .exceptions import MlnativeError
 from .map import Map
 
-__version__ = "0.1.0"
+__version__ = "0.1.0-alpha"
 __all__ = ["Map", "MlnativeError"]

mlnative/_bridge.py

@@ -1,19 +1,19 @@
 """
-Bridge to Bun/JavaScript renderer.
+Bridge to JavaScript renderer.
 
-Handles subprocess communication with the bundled JS renderer.
+Handles subprocess communication with the JS renderer.
+Uses Node.js when available (required for native modules), falls back to Bun.
 """
 
 import json
 import os
+import shutil
 import subprocess
 import sys
 from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
-import pybun
-
 from .exceptions import MlnativeError
 
 
@@ -58,9 +58,55 @@ def get_vendor_dir() -> Path:
             f"Supported platforms: darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-x64"
         )
 
+    # Check that node_modules is actually installed
+    node_modules = vendor_dir / "node_modules" / "@maplibre" / "maplibre-gl-native"
+    if not node_modules.exists():
+        raise MlnativeError(
+            f"Native binaries not installed for {vendor_name}.\n\n"
+            f"To fix, run:\n"
+            f"  cd {vendor_dir} && npm install\n\n"
+            f"Or if using pip, try reinstalling:\n"
+            f"  pip install --force-reinstall mlnative"
+        )
+
     return vendor_dir
 
 
+def _get_js_runtime() -> str:
+    """
+    Get path to JavaScript runtime.
+
+    Prefers Node.js (required for native modules like maplibre-gl-native),
+    falls back to bundled Bun from pybun package.
+    """
+    # First, try to find node in PATH (required for native modules)
+    node_path = shutil.which("node")
+    if node_path:
+        return node_path
+
+    # Fall back to bundled bun from pybun
+    # Note: Bun may not work with all native modules due to V8/JSC differences
+    try:
+        import pybun
+
+        pybun_file = pybun.__file__
+        if pybun_file:
+            bun_path = Path(pybun_file).parent / "bun"
+            if bun_path.exists():
+                return str(bun_path)
+    except ImportError:
+        pass
+
+    raise MlnativeError(
+        "No JavaScript runtime found.\n\n"
+        "Install Node.js (recommended for native module compatibility):\n"
+        "  - macOS: brew install node\n"
+        "  - Linux: apt install nodejs or use nvm\n"
+        "  - Windows: https://nodejs.org/\n\n"
+        "Or install pybun: pip install pybun"
+    )
+
+
 def _validate_png_output(stdout: bytes) -> bytes:
     """Validate that output is valid PNG bytes."""
     if not stdout.startswith(b"\x89PNG"):
@@ -73,16 +119,16 @@ def _validate_png_output(stdout: bytes) -> bytes:
     return stdout
 
 
-def _run_bun_process(
-    bun_path: str, renderer_js: Path, config: dict[str, Any], vendor_dir: Path
+def _run_js_process(
+    runtime_path: str, renderer_js: Path, config: dict[str, Any], vendor_dir: Path
 ) -> bytes:
-    """Execute Bun subprocess and return output."""
+    """Execute JavaScript subprocess and return output."""
     env = os.environ.copy()
     env["MLNATIVE_VENDOR_DIR"] = str(vendor_dir)
 
     try:
         result = subprocess.run(
-            [bun_path, str(renderer_js)],
+            [runtime_path, str(renderer_js)],
             input=json.dumps(config).encode("utf-8"),
             capture_output=True,
             env=env,
@@ -92,11 +138,11 @@ def _run_bun_process(
         raise MlnativeError("Render timeout (60s exceeded)") from None
     except subprocess.CalledProcessError as e:
         stderr = e.stderr.decode("utf-8", errors="replace") if e.stderr else "Unknown error"
-        raise MlnativeError(f"Bun process failed:\n{stderr}") from e
+        raise MlnativeError(f"JS process failed:\n{stderr}") from e
 
     if result.returncode != 0:
         stderr = result.stderr.decode("utf-8", errors="replace")
-        raise MlnativeError(f"Bun render failed:\n{stderr}")
+        raise MlnativeError(f"Render failed:\n{stderr}")
 
     return result.stdout
 
@@ -105,7 +151,7 @@ def render_with_bun(
     config: dict[str, Any], request_handler: Callable[[Any], bytes] | None = None
 ) -> bytes:
     """
-    Render map using Bun subprocess.
+    Render map using JavaScript subprocess.
 
     Args:
         config: Map configuration dict
@@ -123,11 +169,10 @@ def render_with_bun(
     if not renderer_js.exists():
         raise MlnativeError(f"Renderer script not found: {renderer_js}")
 
-    # Get bun path from pybun package (bundled binary)
-    bun_path = str(Path(pybun.__file__).parent / "bun")
+    runtime_path = _get_js_runtime()
 
     # Flag for custom handler (JS side uses temp file protocol)
     config["_hasCustomHandler"] = request_handler is not None
 
-    stdout = _run_bun_process(bun_path, renderer_js, config, vendor_dir)
+    stdout = _run_js_process(runtime_path, renderer_js, config, vendor_dir)
     return _validate_png_output(stdout)

mlnative/_renderer.js

@@ -1,8 +1,9 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 /**
  * MapLibre GL Native renderer for mlnative.
  * 
  * Reads JSON config from stdin, renders map, outputs PNG bytes to stdout.
+ * Works with both Node.js and Bun runtimes.
  */
 
 const fs = require('fs');
@@ -69,47 +70,59 @@ const mapOptions = {
     ratio: config.pixelRatio || 1
 };
 
-// Handle style
-let style = config.style;
-if (typeof style === 'string') {
-    // URL - will be fetched by request handler
-    // Nothing to do
-} else if (typeof style === 'object') {
-    // Inline style object
-    // Already set
-}
-
 // Create and configure map
 const map = new mbgl.Map(mapOptions);
 
-// Load style
-try {
-    map.load(style);
-} catch (e) {
-    console.error(`Failed to load style: ${e.message}`);
-    process.exit(1);
-}
-
-// Render options
-const renderOptions = {
-    zoom: config.zoom,
-    center: config.center,
-    bearing: config.bearing || 0,
-    pitch: config.pitch || 0,
-    width: config.width,
-    height: config.height
-};
-
-// Render
-map.render(renderOptions, (err, buffer) => {
-    if (err) {
-        console.error(`Render error: ${err.message}`);
-        map.release();
+// Function to load style and render
+async function loadStyleAndRender() {
+    let style = config.style;
+    
+    // If style is a URL, fetch it first
+    if (typeof style === 'string' && (style.startsWith('http://') || style.startsWith('https://'))) {
+        try {
+            const response = await fetch(style);
+            if (!response.ok) {
+                throw new Error(`Failed to fetch style: HTTP ${response.status}`);
+            }
+            style = await response.json();
+        } catch (e) {
+            console.error(`Failed to fetch style from ${config.style}: ${e.message}`);
+            process.exit(1);
+        }
+    }
+    
+    // Load style
+    try {
+        map.load(style);
+    } catch (e) {
+        console.error(`Failed to load style: ${e.message}`);
         process.exit(1);
     }
 
-    // Output PNG bytes to stdout
-    process.stdout.write(buffer);
-    map.release();
-    process.exit(0);
-});
+    // Render options
+    const renderOptions = {
+        zoom: config.zoom,
+        center: config.center,
+        bearing: config.bearing || 0,
+        pitch: config.pitch || 0,
+        width: config.width,
+        height: config.height
+    };
+    
+    // Render
+    map.render(renderOptions, (err, buffer) => {
+        if (err) {
+            console.error(`Render error: ${err.message}`);
+            map.release();
+            process.exit(1);
+        }
+        
+        // Output PNG bytes to stdout
+        process.stdout.write(buffer);
+        map.release();
+        process.exit(0);
+    });
+}
+
+// Run
+loadStyleAndRender();