terrana 0.2.0__tar.gz

terrana-0.2.0/.editorconfig

@@ -0,0 +1,22 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{rs}]
+indent_size = 4
+max_line_length = 100
+
+[*.{md,yml,yaml,toml,json}]
+indent_size = 2
+
+[*.py]
+indent_size = 4
+
+[Makefile]
+indent_style = tab

terrana-0.2.0/.gitignore

@@ -0,0 +1,7 @@
+/target
+# Cargo.lock is committed: terrana ships a binary, so a locked dependency set gives
+# reproducible builds. (Library crates typically gitignore it instead.)
+testdata/bench_*.csv
+testdata/bench_*.csv.gz
+.claude/settings.local.json
+/python/tests/__pycache__

terrana-0.2.0/.zenodo.json

@@ -0,0 +1,32 @@
+{
+  "title": "Terrana: Zero-Config Spatial API Server",
+  "description": "<p>Terrana is a zero-config spatial API server written in Rust. Point it at a CSV, Parquet, or GeoJSON file containing lat/lon columns and immediately get a REST API with spatial queries (radius, bounding box, nearest neighbor, point-in-polygon) and geodesic geometry operations (area, convex hull, buffer, dissolve, simplify, distance) &mdash; no database setup, no PostGIS, no infrastructure. Built on DuckDB (bundled) with R-tree spatial indexing and the <code>geo</code> crate for WGS&nbsp;84 geodesic computations.</p>",
+  "upload_type": "software",
+  "license": "MIT",
+  "access_right": "open",
+  "creators": [
+    {
+      "name": "McMeen, John"
+    }
+  ],
+  "keywords": [
+    "spatial",
+    "geospatial",
+    "gis",
+    "rest-api",
+    "duckdb",
+    "rust",
+    "rtree",
+    "spatial-index",
+    "geojson",
+    "wgs84",
+    "geodesic"
+  ],
+  "related_identifiers": [
+    {
+      "identifier": "https://github.com/jmcmeen/terrana",
+      "relation": "isSupplementTo",
+      "scheme": "url"
+    }
+  ]
+}

terrana-0.2.0/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to Terrana will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-06-25
+
+### Added
+
+- **Library crate.** Terrana is now a `lib + bin` crate. `src/lib.rs` exposes a public API so the engine can be used in-process without the HTTP server: `ingest_file`, `detect_lat_lon`, `query`, `AppError`, and the geodesic `geometry` modules.
+- `db::loader::ingest_file` — load a file end to end (stage → detect lat/lon → promote → build the R-tree index) in one call, returning `IngestInfo { lat_col, lon_col, row_count }`.
+- `server` Cargo feature, enabled by default. Depend on Terrana with `default-features = false` to get the pure library without pulling in axum / tokio / tower.
+- **Python bindings** (`terrana` on PyPI, built with PyO3 + maturin). A single stable-ABI (`abi3`) wheel for CPython 3.9+ exposing both an in-process library mode — `load_csv`/`load_parquet`/`load_geojson`, `query_radius`/`query_bbox`/`query_nearest`, `geodesic_distance`/`geodesic_area`, `convex_hull`, `buffer` — and an embedded HTTP server managed from Python (`serve_background`/`serve`/`shutdown`, context manager). The tokio runtime runs entirely in a Rust thread, off the GIL.
+
+### Changed
+
+- Geodesic math moved out of the Axum handlers into pure `terrana::geometry` modules (`area`, `buffer`, `hull`, `dissolve`, `simplify`, `measure`). Handlers are now thin glue; HTTP responses are unchanged.
+
+### Fixed
+
+- `POST /geometry/buffer` reported the area as ~510,000,000 km² (the Earth's entire surface): the ring was wound clockwise, so `geodesic_area_unsigned` measured its complement. The ring is now generated counter-clockwise (GeoJSON right-hand rule), so the reported area is the buffer disk as expected.
+
+## [0.1.1] - 2026-06-02
+
+### Fixed
+
+- `--watch` reloads no longer blank out the dataset when the source file is malformed or half-written mid-save. The new file is now staged and its lat/lon columns validated *before* the live dataset is replaced, so a failed reload leaves the previous data serving and the watcher recovers on the next good write.
+- `testdata/bench.sh` no longer exits non-zero (Error 143) when its background server is terminated on an otherwise successful run, so `make bench` reports success correctly. Genuine failures still propagate.
+- Packaging: `testdata/generate.py` is no longer published to crates.io — the `exclude` glob missed the renamed generator, so benchmark/dev tooling was leaking into the package.
+
+### Changed
+
+- Consolidated the two benchmark data generators into a single `testdata/generate.py` (`--preset bench` for 10K/100K/1M, `--preset 250m` for the 250M-row set); removed `generate_benchdata.py` and `generate_250m.py`.
+- Moved `bench.sh` into `testdata/` (now runnable from any directory) and added `make gen`, `make gen-250m`, and `make bench` targets.
+
+### Added
+
+- Integration tests for `--watch` reload: new rows are reflected, and the old dataset is preserved when a reload hits a bad file.
+
+## [0.1.0] - 2026-06-02
+
+### Added
+
+- CLI with `terrana serve` subcommand and `--lat`, `--lon`, `--port`, `--bind`, `--watch`, `--disk` options
+- Auto-detection of lat/lon columns from common naming conventions
+- File ingestion for CSV, Parquet, GeoJSON, and DuckDB files
+- DuckDB spatial extension R-tree index on geometry column for accelerated spatial queries
+- `--disk` flag for on-disk DuckDB storage — required for large datasets (250M+ rows) that exceed available RAM
+- `GET /query` endpoint with radius, bounding box, and nearest neighbor modes
+- `POST /query/within` for point-in-polygon queries via `ST_Contains` (R-tree accelerated)
+- `select=`, `where=`, `group_by=`, `agg=`, `limit=` query parameters
+- JSON, CSV, and GeoJSON output formats
+- Geometry endpoints: area, convex-hull, centroid, buffer, dissolve, simplify, distance, bounds
+- Geometry area/perimeter use geodesic algorithms (Karney, WGS 84 ellipsoid via `geo` crate)
+- Query path distances (radius, nearest) use haversine via DuckDB `ST_Distance_Sphere`
+- `GET /health`, `GET /schema`, `GET /stats` metadata endpoints
+- CORS support and request tracing via tower-http
+- Tracing/logging with `RUST_LOG` env filter
+- GitHub Actions CI (check, clippy, fmt, cross-platform build) and release workflows
+- Dockerfile and docker-compose.yml for containerized deployment
+- Benchmark script (`bench.sh`) and data generators for 10K–250M row datasets
+- `--watch` now re-ingests the source file and atomically swaps the served dataset on change (previously the flag was accepted but had no effect)
+- Test suite: unit tests for validation, SQL builders, lat/lon detection, and geodesic area; integration tests in `tests/api.rs` exercising the live HTTP API (run with `cargo test -- --include-ignored`)
+- crates.io package metadata (description, license, repository, keywords, categories, MSRV) and dual `MIT OR Apache-2.0` licensing
+- Community files: `CONTRIBUTING.md`, `SECURITY.md`, GitHub issue/PR templates, `.editorconfig`, `rust-toolchain.toml`
+- `Makefile` with shortcuts for build/run/test/lint/package tasks (`make help`)
+- "Installing Rust" guide in the README
+- CI `test` job (runs unit + integration tests); clippy now lints all targets
+
+### Changed
+
+- `GET /stats` returns `null` for `bbox`/`centroid` when the dataset has no spatially-valid rows, instead of a fake `(0, 0)`
+
+### Security
+
+- Column name validation for all user-supplied column names, group_by, agg, and select params
+- Fixed a SQL-injection vector in the `--table` argument for `.duckdb` sources: the table identifier is now validated and quoted before interpolation
+- Bounding-box query parameters are now range-validated (lat ∈ [-90, 90], lon ∈ [-180, 180], min ≤ max)

terrana-0.2.0/CITATION.cff

@@ -0,0 +1,30 @@
+cff-version: 1.2.0
+message: "If you use Terrana in academic research, please cite it using the metadata from this file."
+title: "Terrana: Zero-Config Spatial API Server"
+abstract: >-
+  Terrana is a zero-config spatial API server written in Rust. Point it at a
+  CSV, Parquet, or GeoJSON file containing lat/lon columns and immediately get
+  a REST API with spatial queries and geodesic geometry operations — no database
+  setup, no PostGIS, no infrastructure. Built on axum and DuckDB with R-tree
+  spatial indexing.
+type: software
+authors:
+  - family-names: McMeen
+    given-names: John
+    email: johnmcmeen@gmail.com
+version: 0.1.0
+date-released: 2026-06-02
+doi: 10.5281/zenodo.20515989
+license:
+  - MIT
+  - Apache-2.0
+repository-code: "https://github.com/jmcmeen/terrana"
+url: "https://github.com/jmcmeen/terrana"
+keywords:
+  - spatial
+  - geospatial
+  - geojson
+  - duckdb
+  - rust
+  - rest-api
+  - gis

terrana-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,124 @@
+# Contributing to Terrana
+
+Thanks for your interest in contributing! Terrana is a zero-config spatial API
+server written in Rust, and contributions of all kinds are welcome — bug reports,
+documentation, new file formats, geometry operations, and performance work.
+
+## Ways to contribute
+
+- **Bug reports** — Open an issue describing the problem, the file format you used,
+  and the exact query that triggered it. A minimal sample file helps enormously.
+- **New file formats** — Terrana ingests through DuckDB; adding a format usually
+  means a small addition to [`src/db/loader.rs`](src/db/loader.rs).
+- **Geometry operations** — The geodesic math lives in pure functions under
+  [`src/geometry/`](src/geometry/) (`area.rs`, `buffer.rs`, `hull.rs`, `measure.rs`, …);
+  the `POST /geometry/*` handlers in
+  [`src/handlers/geometry.rs`](src/handlers/geometry.rs) are thin glue over them. All
+  spatial math **must** use geodesic algorithms from the `geo` crate — never
+  planar/Cartesian (see [Geodesic rules](#geodesic-rules) below).
+- **Python bindings** — The PyO3 bindings live in [`python/`](python/) and re-export
+  the same engine; new Python surface goes in [`python/src/lib.rs`](python/src/lib.rs)
+  with a test in [`python/tests/`](python/tests/).
+- **Performance** — Benchmark with `./testdata/bench.sh` (or `make bench`), profile with `cargo flamegraph`,
+  and open a PR with before/after numbers.
+- **Documentation** — Improvements to the README, examples, or inline doc comments
+  are always appreciated.
+
+## Development setup
+
+You'll need a Rust toolchain (stable). If you don't have one, see
+[Installing Rust](README.md#installing-rust) in the README.
+
+```bash
+git clone https://github.com/jmcmeen/terrana.git
+cd terrana
+cargo build
+cargo run -- serve testdata/observations.csv
+```
+
+No system DuckDB or PostGIS is required — DuckDB is bundled. On first run, DuckDB
+downloads its `spatial` extension from the network and caches it locally.
+
+## Before you open a pull request
+
+Run the same checks CI runs, and make sure they all pass:
+
+```bash
+cargo fmt --all                       # format
+cargo clippy --all-targets -- -D warnings   # lint (warnings are errors)
+cargo test                            # unit tests (offline)
+cargo test -- --include-ignored       # + integration tests (needs network)
+```
+
+Or use the [`Makefile`](Makefile) shortcuts (`make help` lists them all):
+
+```bash
+make ci         # fmt-check + lint + unit tests (the offline gate)
+make test-all   # unit + integration tests (needs network)
+make run        # run the server against testdata/observations.csv
+```
+
+The integration tests in [`tests/api.rs`](tests/api.rs) spawn the real binary and
+hit the HTTP endpoints. They are `#[ignore]`d by default because starting the server
+requires the DuckDB `spatial` extension to be available; run them with
+`--include-ignored` in an environment with network access.
+
+For changes to the **Python bindings**, build and test them with
+[uv](https://docs.astral.sh/uv/):
+
+```bash
+cd python
+uv venv --python 3.13 && source .venv/bin/activate
+uv pip install maturin pytest
+maturin develop              # build the extension into the venv
+uv run pytest tests/ -v      # library + server-mode tests
+```
+
+## Pull request guidelines
+
+- Keep PRs focused — one logical change per PR.
+- Add or update tests for any behavior change.
+- Update [`CHANGELOG.md`](CHANGELOG.md) under the `Unreleased` section.
+- Update the README and inline docs when you change user-facing behavior.
+- Write commit messages in the imperative mood ("Add buffer endpoint", not "Added").
+
+## Releasing & versioning
+
+Releases are cut by the maintainer only. The Rust crate and the Python wheel ship
+from a **single `vX.Y.Z` tag** and **share one version**, so:
+
+- **Any change to the Rust crate _or_ the Python bindings needs a version bump** in
+  [`Cargo.toml`](Cargo.toml) at release. crates.io versions are immutable and the
+  wheel version is taken from the tag, so the published version must equal the tag —
+  CI fails the publish if they differ. Follow [SemVer](https://semver.org).
+- Flow: bump `Cargo.toml` → land through `staging` → merge `staging → main` → push
+  `vX.Y.Z` on `main`; the tag publishes both registries.
+
+Contributors don't bump the version in a PR — just note user-facing changes in
+[`CHANGELOG.md`](CHANGELOG.md); the maintainer handles the bump and tag at release.
+
+## Geodesic rules
+
+These are non-negotiable for every geometry calculation:
+
+- **Area / perimeter** → `geo::GeodesicArea::geodesic_area_unsigned()` (Karney, WGS 84).
+- **Buffer ring vertices** → `geo::Destination::geodesic_destination()`.
+- **Geometry-endpoint distances** → `geo::Distance` / geodesic (ellipsoidal).
+- **Query-path distances** (radius, nearest) → DuckDB `ST_Distance_Sphere` (haversine)
+  is acceptable.
+
+Never use planar/Cartesian math for area, distance, or buffer calculations.
+
+## Scope
+
+Terrana is intentionally small. It is **not** a PostGIS replacement, a tile server,
+a distributed system, or a CRS-conversion tool (WGS 84 only). Please open an issue to
+discuss before working on anything that expands this scope — see "What This Project Is
+NOT" in [CLAUDE.md](CLAUDE.md).
+
+## Licensing
+
+Terrana is dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE).
+Unless you state otherwise, any contribution you submit for inclusion in the work, as
+defined in the Apache-2.0 license, shall be dual-licensed as above, without any
+additional terms or conditions.