vl-convert-server

Library crate for serving Vega-Lite and Vega conversions over HTTP. It wraps vl-convert-rs with an axum-based REST API for SVG, PNG, PDF, JPEG, HTML, scenegraph, theme, font, and JavaScript-bundling operations.

This crate does not publish a vl-convert-server binary. The vl-convert package provides vl-convert serve as the reference binary built on this crate. This README is library-first; CLI-specific behavior is called out explicitly.

Library Usage

use vl_convert_rs::converter::VlcConfig;
use vl_convert_server::{bind_listener, build_app, serve, ListenAddr, ServeConfig};

# async fn run() -> Result<(), Box<dyn std::error::Error>> {
let serve_config = ServeConfig {
    main: ListenAddr::Tcp {
        host: "127.0.0.1".to_string(),
        port: 3000,
    },
    ..ServeConfig::default()
};

let built = build_app(VlcConfig::default(), &serve_config).await?;
let listener = bind_listener(&serve_config.main, serve_config.socket_mode).await?;

serve(listener, built, async {
    let _ = tokio::signal::ctrl_c().await;
})
.await?;
# Ok(())
# }

Embedding Checklist

When embedding this crate in another binary, the binary owns process lifecycle policy:

• Use bind_listener rather than binding sockets directly. It handles stale Unix sockets, socket permissions, and cleanup.
• Call build_app before serve. It validates the server config, warms the converter pool, and binds the optional admin listener.
• Pass a shutdown future to serve. Signal handling, parent-process EOF, and drain-timeout escalation are caller responsibilities.
• Install signal handlers before advertising readiness.
• Install tracing yourself or call vl_convert_server::init_tracing. Keep logs on stderr if stdout is reserved for a readiness message or other machine-readable output.
• Harden VlcConfig before calling build_app when serving untrusted input: set data-access policy, V8 heap and execution limits, plugin policy, and Google Fonts controls appropriate for the deployment.

Configuration Model

The library has two configuration layers:

• VlcConfig controls conversion behavior: worker count, data access, JavaScript/V8 limits, themes/locales, plugins, local fonts, Google Fonts, and missing-font policy.
• ServeConfig controls HTTP serving behavior: listeners, bearer auth, CORS, request/body limits, request budgets, Google Fonts cache-miss budget surcharge, proxy trust, logging format, UDS permissions, admin listener settings, and admin reconfiguration drain time.

This crate does not parse environment variables. Embedders decide how to map their own config files, flags, or environment variables onto VlcConfig and ServeConfig.

ServeConfig::default() listens on 127.0.0.1:3000, uses a 30 second request timeout, caps request bodies at 50 MB, leaves auth disabled, leaves budgets disabled, and accepts browser CORS only from loopback origins.

Reference CLI

vl-convert serve is the reference binary for this crate. It adds process behavior around the library:

• VLC_* environment variables and CLI flags for operational server options.
• $PORT fallback for the main TCP port when VLC_PORT/--port are unset.
• SIGINT/SIGTERM handling plus a drain-timeout watchdog.
• Optional --ready-json stdout readiness line.
• Optional parent-close shutdown for subprocess/UDS use.
• --dump-openapi and --dump-openapi=admin one-shot OpenAPI output.

For converter settings, vl-convert serve starts from --vlc-config and then applies CLI/global VLC_* overrides. For server settings, it maps serve flags and env vars directly onto ServeConfig; --vlc-config does not contain ServeConfig fields.

Common vl-convert serve environment variables. Rows that reference VlcConfig are converter settings applied before the server is built; rows that reference ServeConfig are HTTP server settings.

Reference CLI settings with no ServeConfig field:

Related vl-convert serve controls that affect conversion behavior include: VLC_BASE_URL, VLC_ALLOWED_BASE_URLS, VLC_FONT_DIR, VLC_MAX_V8_HEAP_SIZE_MB, VLC_MAX_V8_EXECUTION_TIME_SECS, VLC_AUTO_GOOGLE_FONTS, VLC_GOOGLE_FONT, VLC_GOOGLE_FONT_VARIANT_THRESHOLD, VLC_GOOGLE_FONTS_CACHE_SIZE_MB, VLC_MISSING_FONTS, VLC_EMBED_LOCAL_FONTS, VLC_SUBSET_FONTS, VLC_ALLOW_GOOGLE_FONTS, and VLC_ALLOW_PER_REQUEST_PLUGINS.

Health Endpoints

Admin API

Set ServeConfig.admin to enable a separate admin listener. The reference CLI does this with --admin-port, --admin-host, or --admin-unix-socket.

Admin routes include:

• GET / POST /admin/budget for live budget inspection and updates.
• GET / PATCH / PUT / DELETE /admin/config for live converter config.
• GET / POST / PUT /admin/config/fonts/directories for process font directory state.
• GET / PUT /admin/config/fonts/cache_size for the Google Fonts cache cap.
• GET /admin/diagnostics/workers for per-worker V8 heap statistics.
• /admin/docs and /admin/api-doc/openapi.json for the admin OpenAPI surface.

Admin auth is independent of main API auth. ServeConfig.admin_api_key = None means admin access is gated only by the listener boundary: a loopback IP-literal TCP bind such as 127.0.0.1 / ::1, or UDS filesystem permissions. Non-loopback TCP admin listeners require a non-empty admin API key.

OpenAPI

The library exposes public_openapi() and admin_openapi(). The reference CLI also provides:

vl-convert serve --dump-openapi
vl-convert serve --dump-openapi=admin

Shutdown

The library serve function stops accepting new connections when its shutdown future resolves and waits for spawned server tasks to exit. It does not install signal handlers or enforce a drain deadline.

The reference vl-convert serve binary installs SIGINT/SIGTERM handling and uses VLC_DRAIN_TIMEOUT_SECS / --drain-timeout-secs as the forced shutdown deadline. For UDS/subprocess workflows it can also shut down when the parent closes stdin.