Rossby: The Instant Spatio-Temporal Database

NOTE: Rossby is currently in early development (v0.0.1). The API may change in future releases.

rossby is a blazingly fast, in-memory, NetCDF-to-API server written in Rust.

Instantly serve massive NetCDF datasets as a high-performance HTTP API for point queries and image rendering, with zero data configuration.

Vision

Scientific data is often locked away in static files like NetCDF. rossby liberates this data by providing a simple command-line tool to load a file directly into memory and serve it via a simple, powerful API. It's designed for scientists, engineers, and anyone who needs to interact with spatio-temporal grid data dynamically without the overhead of setting up a traditional database.

Features

In-Memory Performance: Loads the entire dataset into RAM for microsecond-level query latency.
NetCDF Native: Directly reads .nc files without any preprocessing or import steps.
Zero Data-Config: All metadata (variables, dimensions, coordinates) is automatically inferred from the NetCDF file.
High-Performance API: Built with Rust, Axum, and Tokio for incredible speed and concurrency.
On-the-fly Interpolation: Point queries are not limited to the grid; rossby provides interpolated values for any coordinate.
Dynamic Image Generation: Instantly render data slices as PNG or JPEG images for quick visualization.
Flexible Server Configuration: Configure your server via command-line arguments, environment variables, or a JSON file, inspired by uwsgi.
Server Monitoring: Built-in /heartbeat endpoint provides comprehensive server status, including memory usage and uptime.
Service Discovery Ready: Support for service registration and discovery to enable scalable multi-server deployments.

Quick Start

1. Installation

Ensure you have Rust installed. Then, install rossby using cargo:

cargo install rossby

2. Get Sample Data

We'll use a sample weather forecast file for this demo.

# a real climate data file
wget [https://github.com/mountain/rossby/raw/refs/heads/main/tests/fixtures/2m_temperature_1982_5.625deg.nc](https://github.com/mountain/rossby/raw/refs/heads/main/tests/fixtures/2m_temperature_1982_5.625deg.nc)

3. Run `rossby`

Point rossby at your NetCDF file. It's that simple.

rossby 2m_temperature_1982_5.625deg.nc

You should see output indicating the server has started, probably on 127.0.0.1:8000.

INFO  rossby > Loading NetCDF file: "tests/fixtures/2m_temperature_1982_5.625deg.nc"
INFO  rossby > Found 4 variables
INFO  rossby > Found 3 dimensions
INFO  rossby > Data loaded successfully.
INFO  axum::server > Listening on [http://127.0.0.1:8000](http://127.0.0.1:8000)

4. Query the API

Open a new terminal and use curl to interact with your new, instant database.

Get Metadata: Discover what's in the file.

curl http://127.0.0.1:8000/metadata

Get a Point Forecast: Get the interpolated 2-meter temperature (t2m) for a specific location.

There are two ways to query points:

Using time index (legacy method):

curl "http://127.0.0.1:8000/point?lon=139.76&lat=35.68&time_index=0&vars=t2m"
# Expected Response: {"t2m": 288.45}

Using physical value (recommended):

curl "http://127.0.0.1:8000/point?lon=139.76&lat=35.68&time=1672531200&vars=t2m"
# Expected Response: {"t2m": 288.45}

Get an Image: Render an image of the t2m variable for a specific region and time.

curl "http://127.0.0.1:8000/image?var=t2m&time_index=0&bbox=120,20,150,50" -o japan_temp.png
# Now open the generated japan_temp.png file.

Configuration

rossby uses a layered configuration system with the following order of precedence:

Command-Line Arguments (highest priority)
Environment Variables
JSON Config File
Default Values (lowest priority)

CLI Usage:

rossby [OPTIONS] <NETCDF_FILE>

# Example: Run on a public IP, port 9000, with 8 worker threads
rossby --host 0.0.0.0 --port 9000 --workers 8 my_data.nc

# Enable service discovery
rossby --discovery-url http://discovery-service:8080/register my_data.nc

JSON Configuration:

You can specify a config file with the --config flag. rossby --config server.json

server.json example:

{
  "server": {
    "host": "0.0.0.0",
    "port": 9000,
    "workers": 8,
    "discovery_url": "http://discovery-service:8080/register"
  },
  "data": {
    "interpolation_method": "bilinear",
    "file_path": "/path/to/data.nc"
  }
}

API Reference

GET /metadata: Returns JSON describing all variables, dimensions, and attributes of the loaded file.
GET /point: Returns interpolated values for one or more variables at a specific point in space-time. Supports querying by physical value or raw index.
GET /image: Returns a PNG/JPEG image rendering of a variable over a specified region and time.
GET /heartbeat: Returns server status information including uptime, memory usage, and dataset details.
- Response includes:
  - server_id: Unique identifier for this server instance
  - timestamp: Current time in ISO 8601 format
  - uptime_seconds: Server uptime in seconds
  - memory_usage_bytes: Process memory usage (if available)
  - available_memory_bytes: Available system memory (if available)
  - status: Server health status ("healthy" under normal conditions)
  - dataset: Object containing dataset information:
    - file_path: Path to the loaded NetCDF file
    - variable_count: Number of variables in the dataset
    - variables: List of variable names
    - dimension_count: Number of dimensions
    - dimensions: List of dimension names and sizes
    - data_memory_bytes: Approximate memory usage of the dataset
GET /image: Returns a PNG/JPEG image rendering of a variable over a specified region and time.
- var: (required) Variable name to render
- time_index: (optional) Time index, defaults to 0
- bbox: (optional) Bounding box as "min_lon,min_lat,max_lon,max_lat"
- width: (optional) Image width in pixels, defaults to 800
- height: (optional) Image height in pixels, defaults to 600
- colormap: (optional) Colormap name (e.g., viridis, plasma, coolwarm), defaults to "viridis"
- format: (optional) Output format: "png" or "jpeg", defaults to "png"
- center: (optional) Map centering: "eurocentric" (-180° to 180°), "americas" (-90° to 270°), "pacific" (0° to 360°), or a custom longitude value, defaults to "eurocentric"
- wrap_longitude: (optional) Allow bounding boxes that cross the dateline/prime meridian, defaults to false
- resampling: (optional) Upsampling/downsampling quality: "nearest", "bilinear", "bicubic", or "auto", defaults to "auto" (bilinear)

For full details, see the documentation included in the repository.

Building from Source

git clone https://github.com/mountain/rossby.git
cd rossby
cargo build --release
./target/release/rossby --help

Development

Continuous Integration

This project uses GitHub Actions for continuous integration. The CI pipeline runs the following checks on every push and pull request:

cargo check - Verifies the code compiles without errors
cargo test - Runs all tests to ensure they pass
cargo clippy - Performs static analysis to catch common mistakes
cargo fmt --check - Ensures code adheres to formatting standards

You can see the CI configuration in the .github/workflows/ci.yml file.

Git Hooks

To ensure code quality before commits are made, we provide Git hooks in the hooks/ directory. These hooks automatically run tests and other checks before allowing commits.

To install the hooks, follow the instructions in the hooks/README.md file.

Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.

Before submitting a PR, please make sure:

All tests pass (cargo test)
The code is properly formatted (cargo fmt)
There are no clippy warnings (cargo clippy)
You've added tests for any new functionality

License

This project is licensed under either of

Apache License, Version 2.0
MIT license

at your option.

rossby 0.0.1