sparkless-server

sparkless-server is the native, read-only HTTP SQL service for Robin Sparkless 4.16. It executes the accepted SQL directly through robin-sparkless and needs neither Python nor a JVM. Spark Connect, user-defined functions, named tables, file/network readers, DDL, and DML are not available in this release.

Run

cargo run --locked -p sparkless-server -- serve

The service binds to 127.0.0.1:8099. Set --bind 0.0.0.0 only in a trusted network deployment. --port 0 asks the OS for an available port. Bind, port, and resource-limit options have corresponding SPARKLESS_SERVER_* environment variables; explicit CLI values override environment values. The launcher-only --control and --launch-id flags are command-line options. Zero, contradictory, and above-ceiling resource limits fail startup.

When launched by Python, use --control --launch-id <id>. The child writes a bounded JSON-lines readiness record to stdout after binding and executing a native SELECT 1 witness. Shutdown is requested through the matching launch ID on stdin. Diagnostics go to stderr.

Container image

Build the JVM-free Linux image from the repository root:

docker build -f crates/sparkless-server/Dockerfile -t sparkless-server:4.16.0 .
docker run --rm -p 127.0.0.1:8099:8099 sparkless-server:4.16.0

The image runs as an unprivileged user and listens on 0.0.0.0:8099 inside the container. It contains the server executable and its native runtime libraries; it does not contain Python or a JVM. The release workflow publishes the Linux x86_64 image as ghcr.io/eddiethedean/sparkless-server:4.16.0 and updates the latest tag after the release checks pass.

HTTP contract

• GET /live reports process liveness.
• GET /health reports ready only after listener binding and native startup.
• GET /capabilities reports the HTTP SQL subset and active limits.
• POST /statements accepts {"session":"...","kind":"sql","code":"SELECT ..."}.
• POST /close accepts {"session":"..."} and cancels that session's work.

Successful statements return ordered schema fields and positional scalar rows. Errors from SQL execution use the statement-agent error envelope; malformed transport requests use HTTP errors. Results are fully bounded before success headers are sent.

Sessions are isolated, process-local, and read-only. Their configuration is fixed to Spark 4.0 compatibility, ANSI mode, case-insensitive resolution, and UTC. The reserved sql-warehouse session does not expire while the service is running. Closing a session cancels cooperatively and does not forcibly stop native code.

The accepted SQL forms are SELECTs over literals and constant derived queries, bounded UNION ALL, basic scalar arithmetic/comparison/boolean expressions, CAST, IS NULL, WHERE, output-column ORDER BY, and literal LIMIT. Supported results are BOOLEAN, SMALLINT, INT, BIGINT, finite DOUBLE, STRING, DATE, microsecond UTC TIMESTAMP, and DECIMAL(1..38, scale 0..precision), including typed nulls. Capabilities and actual configured limits are available from the server itself. These capabilities are intentionally narrower than the embedded Sparkless API.

See the 4.16 release plan for native release gates and optional SDK/emulator certification status.