speasy-proxy

A fast caching proxy server for speasy, reducing load on upstream data providers (AMDA, CDAWeb, SSCWeb) and improving response times for space physics data access.

speasy-proxy is speasy behind HTTP. Each request runs through the same speasy library you use on your laptop, with its own cache. So one fetch from a provider serves every user who asks for the same data after it.

A request goes down the layers until one has the data:

Inventories (the product trees) take the same path: speasy downloads them from the proxy, already parsed, instead of crawling every provider.

The speasy inside the proxy is a normal speasy. So it uses a proxy too, and by default that is the public one. A speasy-proxy you deploy is therefore already a layer in front of the public instance, with no configuration. Add more layers the same way, as many as you want:

• Each layer caches. The layer closest to the user answers first. A lab proxy keeps a busy team's data on the local network.
• Each layer can add its own data. The archive provider never goes through a proxy. A lab proxy therefore serves its own files (see docs/hapi-server.md) next to everything upstream.
• SPEASY_PROXY_URL points a layer at another proxy than the public one. SPEASY_PROXY_ENABLED=false makes it talk to the providers directly instead.
• Clients don't see any difference. They talk to the nearest layer like to any speasy-proxy.

A public instance is available at: https://sciqlop.lpp.polytechnique.fr/cache/

speasy uses this proxy by default — no configuration needed. You can browse the available data and interactive API docs at that URL.

BASE=https://sciqlop.lpp.polytechnique.fr/cache
# One hour of ACE IMF from AMDA, as JSON
curl "$BASE/get_data?path=amda/imf&start_time=2020-01-01T00:00:00&stop_time=2020-01-01T01:00:00&format=json"
# Same, as an ISTP CDF file (keeps all metadata)
curl -OJ "$BASE/get_data?path=amda/imf&start_time=2020-01-01T00:00:00&stop_time=2020-01-01T01:00:00&format=cdf"
# At most ~2000 points per component, server-side downsampled
curl "$BASE/get_data?path=amda/imf&start_time=2020-01-01&stop_time=2020-02-01&format=json&max_points=2000"

• path is <provider>/<product id>. Browse /plot to find one: the selected product's path shows under the search box, and its Code button prints ready-made requests.
• Times are ISO-8601 (UTC when no offset is given) or Unix epoch seconds.
• Formats: json and cdf are language-neutral. python_dict and speasy_variable are Python pickles (what speasy itself uses). html_bokeh is an interactive plot page.
• JSON: fill values and NaN are null; times (axes[0].values) are int64 nanoseconds since 1970-01-01 UTC — parse them as 64-bit integers, not floats.
• Errors are JSON {"error", "detail"}: 400 bad time range, 404 unknown provider/product, 422 invalid parameter, 502 upstream provider failure.

Want a HAPI server over your own files? See docs/hapi-server.md: a YAML file describing them, an optional codec, and SPEASY_PROXY_HAPI_ONLY=true.

Podman is recommended, but Docker works too.

# Build the image
./docker/build.sh [PORT] [NAME] [SPEASY_PACKAGE]

# Run with Podman (--stop-timeout must exceed gunicorn's 30 s graceful timeout,
# otherwise a stop SIGKILLs requests still in flight; podman's default is 10 s)
podman run -d -p 6543:6543 --stop-timeout 40 \
  -v speasy-cache:/data \
  -v speasy-index:/index \
  speasy_proxy

Requires uv.

uv sync

# Development
uv run uvicorn speasy_proxy:app --reload

# Production
uv run gunicorn speasy_proxy:app -k speasy_proxy.UvicornWorker.SpeasyUvicornWorker

All settings are controlled via environment variables:

The full interactive API documentation is available at /docs on any running instance.

Key endpoints:

uv sync --dev
uv run pytest

MIT