planisphere 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0f892c4538b11a9eaea839ce16b677e0034b04540040dd9cecd7f81465f5ed07
+  data.tar.gz: c792adef698e4a0ce0711a81612779fafa278f3a72c3ed70de697fd4b903eac1
+SHA512:
+  metadata.gz: 98b61037052e9e549f0d1ccd8fc1d94e8c63757907adab7bb3178df18f0a555b3313561667a734c48d82f522cc7c9fc4c964f8f9041c346eed324f6c9b727798
+  data.tar.gz: 71ed9d21706d7a5451d86f0ce5cca2528b9da5cc53f1ecaa79e1ef3b1d8ce4707734a57cc843ee59c5b6203167c372054a7abc132f5514c8fd972ae939f77a93

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Abdelkader Boudih
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,546 @@
+# planisphere
+
+A headless map server for **PostGIS**. Your layers are SQL functions;
+planisphere serves them as vector tiles, OGC API Tiles, and WMS images. It's a modern
+replacement for `mapserv`-style CGI servers. No mapfiles, no GDAL, no GUI.
+
+- **Vector tiles** (MVT) with TileJSON 3.0, ETags, gzip
+- **OGC API - Tiles** with the `WebMercatorQuad` tile matrix set (passes the OGC conformance suite)
+- **WMS 1.3.0 / 1.1.1** `GetMap` (PNG, PNG8, JPEG) with labels, and `GetFeatureInfo`,
+  rendered server-side and styled with a MapLibre style (passes the OGC WMS 1.3.0 suite)
+- **Resilient**: adaptive concurrency with queue shedding, circuit breaker around PostGIS,
+  startup backoff, per-client rate limits
+- **Observable**: live `/status` dashboard, readiness probe, and an admin MCP endpoint
+- **PostgreSQL 18 + PostGIS 3.6 only**: no compatibility layers for older versions
+
+## Quick start
+
+```sh
+docker compose up --build
+```
+
+Open <http://127.0.0.1:8080/viewer> for a map of the demo layers and
+<http://127.0.0.1:8080/status> for live server state. The database starts with sample data
+from [`dev/fixtures.sql`](dev/fixtures.sql) (loaded once, on a fresh volume).
+
+To develop against the same database with cargo:
+
+```sh
+docker compose up -d postgis
+cargo run -- -c planisphere.example.toml serve
+```
+
+## Layers are SQL functions
+
+Any function in a configured schema with this signature becomes a layer, named after the function:
+
+```sql
+fn(z integer, x integer, y integer [, query json | jsonb]) RETURNS bytea
+```
+
+It's the same contract as Martin and pg_tileserv, so existing functions work unchanged:
+
+```sql
+CREATE FUNCTION tiles.roads(z integer, x integer, y integer)
+RETURNS bytea LANGUAGE sql STABLE PARALLEL SAFE AS $$
+  SELECT ST_AsMVT(t, 'roads', 4096, 'geom') FROM (
+    SELECT name, ST_AsMVTGeom(geom, ST_TileEnvelope(z, x, y), 4096, 64) AS geom
+    FROM roads
+    WHERE geom && ST_TileEnvelope(z, x, y, margin => 64.0 / 4096)
+  ) t WHERE geom IS NOT NULL
+$$;
+
+COMMENT ON FUNCTION tiles.roads(integer, integer, integer) IS
+  '{"description": "Road network", "minzoom": 4, "maxzoom": 16,
+    "vector_layers": [{"id": "roads", "fields": {"name": "String"}}]}';
+```
+
+- **Metadata** is optional JSON in the function comment: `title`, `description`,
+  `attribution`, `minzoom`, `maxzoom` (≤ 24), `bounds` (WGS84 `[w, s, e, n]`; a
+  single-point extent is widened by 0.0001°), `vector_layers`. A plain-text comment
+  becomes the description.
+- **Query parameters** reach the optional `query` argument as JSON, so
+  `/tiles/roads/10/512/340.mvt?kind=motorway` sees `{"kind": "motorway"}`.
+- Mark functions `STABLE PARALLEL SAFE`, not `IMMUTABLE`, since they read tables.
+- Use `&&` against an envelope **in the table's SRID**. Transforming the indexed column
+  (`ST_Transform(geom, 3857) && …`) disables the spatial index.
+- Return an empty `bytea` for an empty tile; planisphere answers `204 No Content`.
+
+`planisphere check` lists the layers it found.
+
+The scripts in [`sql/`](sql) create their helpers in a `planisphere` schema. PostgreSQL's
+default `search_path` is `"$user", public`, so a role named `planisphere` creates its
+unqualified tables in that schema instead of `public`. Don't run application code as a
+role called `planisphere`, or pin it:
+`ALTER ROLE planisphere IN DATABASE <db> SET search_path = public;`.
+
+### Live layers
+
+Create, change or drop a tile function and planisphere picks it up without a restart. Each
+reload rediscovers layers and extensions and reloads the WMS style file, then swaps the whole
+catalog atomically. In-flight requests finish on the catalog they started with. A reload that
+fails (for example, a broken style) is logged and the current catalog keeps serving.
+
+There are three ways to reload:
+
+- **Automatically:** install [`sql/planisphere-reload.sql`](sql/planisphere-reload.sql). An event
+  trigger sends `NOTIFY planisphere_reload` on function, comment, grant and extension DDL.
+  planisphere listens on a dedicated connection, coalesces bursts (such as a migration) into
+  one reload, and catches up after reconnecting. Event triggers need a superuser; on
+  Amazon RDS, install it as the master user. Drop the trigger before a major-version
+  upgrade, and run DDL against the primary, since read replicas don't fire event triggers.
+- `kill -HUP <pid>`, or `NOTIFY planisphere_reload` from any session.
+- The MCP `reload` tool, which also reports what changed.
+
+`/status` shows the catalog generation and when it was loaded.
+
+## Query functions
+
+Request-shaped work that isn't a tile (routes, lookups, statistics) uses a second
+contract, discovered the same way in `[functions] schemas` (default `["api"]`):
+
+```sql
+fn(params jsonb) RETURNS jsonb
+```
+
+- `GET /functions/{name}?a=1&b=2` passes `{"a": "1", "b": "2"}`, and
+  `POST /functions/{name}` passes the JSON body. `GET /functions` lists them.
+- They follow the same rules as tile functions: `"public": true` in the comment, verified
+  claims set in the transaction (so row-level security applies), `statement_timeout`,
+  the circuit breaker, and hot reload.
+- A `RAISE EXCEPTION` (or a data error) returns `400` with the function's message, for
+  example "no route between those points". Other failures return `500`.
+- A result whose `type` is `FeatureCollection` is served as `application/geo+json`.
+
+The demo fixtures route over a street grid with pgRouting
+(`/functions/route?from=4.405,51.882&to=4.545,51.955`). They use only functions
+present in both pgRouting 3.8 (Amazon RDS) and 4.0.
+
+## Authentication and tenant isolation
+
+Each app signs its own users' tokens, planisphere verifies them, and PostgreSQL enforces
+isolation. planisphere never sees your user database.
+
+1. **Your app mints a short-lived JWT** (5–15 minutes) after its own login. It must be
+   signed with an asymmetric key (`EdDSA`, `ES256`/`ES384`, `RS*`, `PS*`); `HS*` tokens
+   are always refused, because holding a verification key must never let anyone mint
+   tokens. Required claims are `iss`, `aud` (`planisphere`) and `exp`; `nbf` is checked
+   if present. Add `sub`, `tenant`, and anything your policies need, such as `roles` or
+   `nation`.
+2. **planisphere verifies it** against `[[auth.issuers]]`: a PEM public key, a JWKS file,
+   or a JWKS URL, with keys selected by `kid` for rotation. Key files are re-read on
+   `SIGHUP` or the MCP `reload` tool. A `jwks_url` is fetched at startup (planisphere
+   won't start if it can't be fetched), then refetched every `jwks_refresh_secs`
+   (default 300). A token naming an unknown `kid` triggers an early refetch, at most once
+   every 30 seconds, and gets a `401` until then. To rotate, publish the new key before
+   signing with it. A failed refresh keeps the last good keys. Use `https://`; plain
+   `http://` is only accepted for loopback addresses. Clients send
+   `Authorization: Bearer <token>`; with MapLibre, set it in `transformRequest`.
+3. **PostgreSQL enforces isolation.** planisphere runs each authenticated tile query in a
+   transaction with `request.jwt.claims` set to the verified claims. Install
+   [`sql/planisphere-auth.sql`](sql/planisphere-auth.sql) and write policies with its helpers:
+
+   ```sql
+   ALTER TABLE depots ENABLE ROW LEVEL SECURITY;
+   CREATE POLICY depots_tenant ON depots FOR SELECT USING (tenant = planisphere.tenant());
+   ```
+
+   Outside an authenticated request the helpers return `NULL`, so policies fail closed.
+
+Rules that follow:
+
+- A layer marked `"public": true` in its comment needs no token. Every other layer
+  returns `401` without a valid token, and an invalid token is always a `401`.
+- Authenticated responses are `Cache-Control: private` with `Vary: Authorization`, so a
+  CDN never serves one tenant's tiles to another.
+- **planisphere refuses to start** with auth on when its database role is a superuser or
+  `BYPASSRLS`, because row-level security would silently not apply. It also warns about
+  RLS tables the role owns without `FORCE ROW LEVEL SECURITY`, and about
+  `SECURITY DEFINER` tile functions, which run as their owner.
+- `planisphere token --key k.pem --iss dev --tenant acme` mints a token for development.
+  `dev/keys.sh` creates a dev keypair.
+- The MCP `probe_tile` tool takes `claims` (for example `{"tenant": "acme"}`) to show
+  what a tenant would see.
+
+The demo fixtures include `tiles.depots`, protected by row-level security, with rows for
+two tenants.
+
+## Live updates
+
+Maps repaint when your data changes, without polling.
+
+1. Install [`sql/planisphere-changes.sql`](sql/planisphere-changes.sql) and attach its trigger
+   to the tables behind a layer, naming the layer and, optionally, the tenant column:
+
+   ```sql
+   CREATE TRIGGER depots_changed AFTER INSERT OR UPDATE OR DELETE ON depots
+     FOR EACH ROW EXECUTE FUNCTION planisphere.notify_layer_change('depots', 'tenant');
+   ```
+
+   Or call `planisphere.notify_change(layer, tenant, bbox)` yourself. Notifications go out
+   at `COMMIT`, so nothing is sent for a rollback. Identical ones collapse per transaction:
+   a bulk update costs one event per (layer, tenant), not one per row.
+2. Clients subscribe to `GET /events` (SSE), optionally with `?layers=a,b`. The stream
+   carries these events:
+   - `ready`;
+   - `change` (`{"layer", "bbox"?}`): refetch that layer, for example with MapLibre's
+     `map.refreshTiles(layer)`;
+   - `catalog`: layers were added or changed;
+   - `resync`: the client fell behind, so refetch everything;
+   - `expired`.
+3. Each event reaches only clients allowed to read the layer. A change with a `tenant`
+   reaches only that tenant, and events never carry tenant ids. `EventSource` cannot set
+   headers, so `/events` also accepts `?access_token=`. The stream closes when the token
+   expires; reconnect with a fresh one.
+
+`/viewer` subscribes automatically; add `?token=<jwt>` to see protected layers.
+
+### Tile cache
+
+Tiles are cached in memory (`tiles.cache_max_mb`, default 256 MB), keyed by layer, tile,
+query and the caller's claims. Two users of one tenant with different roles never share
+an entry, because row-level security may read any claim. Concurrent requests for the same
+uncached tile share one database query.
+
+- A `change` event refreshes that layer for the affected tenant. Other tenants keep
+  their cached tiles.
+- A catalog reload (any function DDL) drops everything.
+- `tiles.cache_ttl_secs` (default 1 hour) bounds staleness for data changed without a
+  trigger.
+
+Invalidation bumps version counters rather than deleting entries, so a query that was
+already running when the change committed can never serve its stale result to anyone
+afterwards. `/status` shows the hit rate and size.
+
+## Extensions
+
+PostGIS is the only requirement. planisphere also detects the established extensions it can
+build on: h3, pgRouting, pgvector, pg_cron, pg_partman, pgTAP, hypopg, pg_repack and others.
+Features use these rather than reimplementing them. Every extension on the list is available
+on Amazon RDS for PostgreSQL 18, so nothing locks you out of managed Postgres (which is why
+TimescaleDB is not on the list). `planisphere check`, `/status` and the MCP `status` tool show
+what is installed, what could be, and version caveats. For example, pgRouting 4.x removed
+`pgr_createTopology`, which RDS's 3.8 still has.
+
+## Endpoints
+
+| Path | What |
+|---|---|
+| `/tiles` | layer list |
+| `/tiles/{layer}.json` | TileJSON 3.0 |
+| `/tiles/{layer}/{z}/{x}/{y}.mvt` | vector tile |
+| `/fonts/{fontstack}/{start}-{end}.pbf` | MapLibre glyph range, generated from the label font |
+| `/`, `/conformance`, `/api` | OGC API landing page, conformance classes, OpenAPI 3.0 |
+| `/collections/{layer}/tiles/WebMercatorQuad/{tileMatrix}/{tileRow}/{tileCol}` | OGC API tile |
+| `/tileMatrixSets/WebMercatorQuad` | tile matrix set definition (OGC 17-083r4) |
+| `/wms` | WMS 1.3.0 / 1.1.1: `GetCapabilities`, `GetMap`, `GetFeatureInfo`, `GetLegendGraphic` |
+| `/functions`, `/functions/{name}` | query functions (`GET` params or `POST` JSON) |
+| `/events` | live `change` / `catalog` events (SSE), filtered per tenant |
+| `/viewer` | MapLibre map of every layer, refreshed live |
+| `/status` | live dashboard (Datastar over SSE) |
+| `/metrics` | Prometheus metrics |
+| `/health`, `/ready` | liveness; readiness is 503 while the database circuit is open |
+| `/mcp` | admin MCP endpoint (see below) |
+
+Errors are `application/problem+json`, except WMS, which returns OGC XML exception reports.
+
+## WMS
+
+`GetMap` renders from the same tile functions: it fetches the tiles a MapLibre client would
+load for the requested view, then draws them with [tiny-skia](https://github.com/linebender/tiny-skia).
+Supported CRSs are `EPSG:3857`, `EPSG:4326` and `CRS:84`. For `EPSG:4326` the BBOX is lat,lon
+in 1.3.0 and lon,lat in 1.1.1, as the specs require. `FORMAT` is `image/png`,
+`image/png; mode=8bit` (palette PNG, also `image/png8`; usually a third of the size) or
+`image/jpeg` (opaque: `TRANSPARENT` is ignored).
+
+`GetFeatureInfo` fetches the one tile under the clicked pixel for each `QUERY_LAYERS`
+entry, at the zoom `GetMap` used, so it's normally a cache hit. It reports the features
+drawn there, topmost first:
+
+- polygons that contain the pixel;
+- lines and circles within their styled width plus 3 px.
+
+Style filters apply, so hidden features are never reported. `INFO_FORMAT` is
+`text/plain`, `text/html`, `text/xml`, `application/json` or `application/geo+json`;
+the JSON forms include lon/lat geometry at tile resolution. `FEATURE_COUNT` is capped
+at 50.
+
+Styling uses a [MapLibre style](https://maplibre.org/maplibre-style-spec/) (`[wms] style`).
+Each source name is a planisphere layer id, and `source-layer` is the MVT layer inside it.
+Without a style file every layer gets an automatic one. The supported subset:
+
+- **Layer types:** `background`, `fill`, `line`, `circle`, `symbol` (text and icons)
+- **Expressions:** `get`, `has`, `geometry-type`, `zoom`, comparisons, `all`, `any`, `!`, `case`,
+  `match`, `coalesce`, `to-number`, `to-string`, `concat`, `upcase`, `downcase`, `step`,
+  `interpolate` (`linear`, `exponential`)
+
+**Labels** come from `symbol` layers:
+
+- **Text:** `text-field`, as an expression or a `"{name}"` template.
+- **Layout:** `text-size`, `text-anchor`, `text-offset`, `text-transform`,
+  `text-max-width` (wraps at spaces), `text-allow-overlap`, `symbol-placement`,
+  `symbol-spacing` and `text-max-angle`.
+- **Paint:** `text-color`, `text-opacity`, `text-halo-color` and `text-halo-width`.
+
+Placement:
+
+- Labels are placed after all geometry, topmost layer first, and a label that would
+  collide with one already placed is dropped.
+- A label cut by the image edge is dropped too, so tiled WMS clients never show half
+  a label.
+- With `symbol-placement: point` (the default), points are labelled at the point, lines
+  at their midpoint, polygons at the centroid of their largest part.
+- With `symbol-placement: line`, labels follow lines and polygon outlines glyph by glyph,
+  repeating every `symbol-spacing` px (default 250). They always read left to right, and
+  vertical lines read bottom to top. A label is dropped where the line bends more than
+  `text-max-angle` (default 45°) between two glyphs, or where it's longer than the line.
+  `line-center` places one label at the middle of each line.
+
+`text-font` is ignored. The bundled font is Noto Sans (Latin, Greek, Cyrillic; SIL OFL);
+point `[wms] font` at another TrueType/OpenType file for other scripts. There is no text
+shaping, so scripts that need it (Arabic, Indic) render unjoined.
+
+**Icons** come from the style's `sprite`: a local path without extension, resolved
+relative to the style file, naming `<path>.json` and `<path>.png` (MapLibre's sprite
+format). Remote sprite URLs aren't fetched.
+
+- **Properties:** `icon-image` (an expression, so `match` or `step` can pick an icon
+  per feature), `icon-size`, `icon-anchor`, `icon-offset`, `icon-opacity` and
+  `icon-allow-overlap`. SDF icons are tinted with `icon-color`.
+- **With text:** a symbol can have an icon, text, or both. With both, they're placed
+  together, so both fit or neither is drawn.
+- **Limits:** icons need `symbol-placement: point`.
+- **Legends:** legends show icons, one row per class when `icon-image` depends on a
+  property.
+
+**Glyphs for MapLibre clients:** planisphere serves the label font as MapLibre glyph
+ranges, so client-side styles can draw text without a font CDN:
+
+```json
+"glyphs": "https://maps.example.com/fonts/{fontstack}/{range}.pbf"
+```
+
+Every fontstack name gets the same font: `[wms] font`, else the bundled Noto Sans.
+The glyphs are signed distance fields made the way MapLibre's TinySDF makes them.
+Each range is rendered once and cached for the life of the process.
+
+Unsupported style syntax is rejected at startup, naming the layer. See
+[`dev/style.json`](dev/style.json) for an example.
+
+`GetLegendGraphic` draws one row per style layer of `LAYER`, with a swatch in its own
+paint. A colour driven by a property (`interpolate`, `step` or `match` over `get`) becomes
+one row per stop or category, such as `< 5,000,000` or `motorway, trunk`. `SCALE` picks
+the zoom; otherwise the legend is drawn at zoom 10. `WIDTH`/`HEIGHT` size the swatches,
+and `TRANSPARENT` and `BGCOLOR` work as in `GetMap`. Each layer's style advertises its
+legend through `LegendURL`, which QGIS and web clients pick up.
+
+
+## Configuration
+
+`planisphere -c <file>` (or `$PLANISPHERE_CONFIG`, default `planisphere.toml`).
+[`planisphere.example.toml`](planisphere.example.toml) documents every option. The main ones:
+
+| Key | Default | |
+|---|---|---|
+| `listen` | (required) | address to bind |
+| `public_url` | from `Host` | base URL used in links |
+| `database.url` | (required) | overridden by `$PLANISPHERE_DATABASE_URL` |
+| `database.pool_size` | 8 | |
+| `database.statement_timeout_ms` | 10000 | per connection; 0 disables |
+| `database.connect_attempts` | 10 | `serve` retries startup with exponential backoff |
+| `database.breaker.*` | 5 failures / 30 s, open 10 s | trips only on database-health errors |
+| `tiles.queue_target_ms`, `queue_interval_ms` | 50, 500 | shed tile queries once waits stay above target for a whole interval |
+| `tiles.queue_max_wait_ms` | 2000 | longest any tile query waits for a slot |
+| `tiles.schemas` | `["public"]` | where tile functions are discovered |
+| `rate_limit.requests_per_sec`, `burst` | 50, 100 | per client IP; 0 disables |
+| `rate_limit.trust_x_forwarded_for` | false | enable only behind a proxy that sets it |
+| `wms.style` | automatic | MapLibre style file, relative to the config file |
+| `wms.max_size`, `max_tiles` | 4096, 64 | GetMap limits |
+| `wms.font` | bundled Noto Sans | Label font (TrueType/OpenType), relative to the config file |
+| `mcp.enabled`, `token_env` | true, `PLANISPHERE_MCP_TOKEN` | |
+
+`RUST_LOG` controls logging (default `info`).
+
+### Database TLS
+
+TLS is configured with libpq parameters in `database.url`, which mean what libpq says
+they mean:
+
+| `sslmode` | encrypted | server verified |
+|---|---|---|
+| `disable` | no | – |
+| `prefer` (default) | if the server offers it | no |
+| `require` | yes | no, unless `sslrootcert` is set (then like `verify-ca`) |
+| `verify-ca` | yes | certificate chain |
+| `verify-full` | yes | chain and host name |
+
+`sslrootcert` names the CA file; without it, the system trust store is used.
+`sslcert` and `sslkey` enable client certificates. For Amazon RDS, download the
+[RDS CA bundle](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html)
+and use `?sslmode=verify-full&sslrootcert=/path/to/global-bundle.pem`. Every
+certificate in the bundle is trusted. planisphere logs a warning whenever the server
+certificate is not verified.
+
+### RDS IAM authentication
+
+With `database.iam_auth = true`, planisphere authenticates to RDS with IAM instead of a
+stored password. It needs TLS (`sslmode=require` or stricter) and a database user granted
+`rds_iam`:
+
+```toml
+[database]
+url = "postgres://planisphere_reader@mydb.abc123.eu-west-1.rds.amazonaws.com/gis?sslmode=verify-full&sslrootcert=/etc/ssl/rds-global-bundle.pem"
+iam_auth = true
+region = "eu-west-1"      # else $AWS_REGION / $AWS_DEFAULT_REGION
+```
+
+```sql
+CREATE ROLE planisphere_reader LOGIN;
+GRANT rds_iam TO planisphere_reader;
+```
+
+- **Tokens:** each new connection, pooled or the `LISTEN` one, signs a 15-minute token
+  (the same token `aws rds generate-db-auth-token` prints). A token is reused for up to
+  10 minutes.
+- **Credentials:** found the way the AWS SDKs find them:
+  - `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (/ `AWS_SESSION_TOKEN`);
+  - EKS IRSA (`AWS_WEB_IDENTITY_TOKEN_FILE` + `AWS_ROLE_ARN`, exchanged with STS);
+  - the ECS task role or EKS Pod Identity endpoint;
+  - EC2 instance metadata (IMDSv2).
+- **Caching and limits:** temporary credentials are cached until five minutes before
+  they expire. Profiles and SSO aren't read, and no AWS SDK is linked.
+- **The IAM policy** needs `rds-db:connect` on
+  `arn:aws:rds-db:<region>:<account>:dbuser:<resource id>/planisphere_reader`.
+
+## Metrics
+
+`/metrics` serves Prometheus text format. It is not rate-limited and needs no token. It
+includes:
+
+- tile requests by outcome;
+- cache hits, misses, entries and bytes;
+- circuit state and pool use;
+- open event streams and delivered events, and whether the `LISTEN` connection behind them
+  and hot reload is up (`planisphere_listener_connected`);
+- catalog reloads and generation;
+- `planisphere_tile_db_seconds{layer}`, a histogram of database time per layer (cache
+  misses only).
+
+### Admission control
+
+How many tile queries run at once is learned, not configured
+([shed-machines](https://crates.io/crates/shed-machines)):
+
+- **The limit** starts at one query per pooled connection. It grows by one each time a
+  query succeeds with every slot busy, up to `database.breaker.max_concurrency`
+  (default 4 per pooled connection). It drops to three quarters on overload: a pool
+  wait timeout, a statement timeout, or a lost connection. Latency alone doesn't move
+  it, because layers legitimately differ a hundredfold.
+- **Requests over the limit wait** instead of failing, because a map view asks for dozens
+  of tiles at once and MapLibre doesn't retry a refused tile. They're served in arrival
+  order, so a new request never overtakes one already waiting. CoDel watches those waits:
+  a burst passes, but once waits stay above `tiles.queue_target_ms` for a whole
+  `tiles.queue_interval_ms`, requests are shed with `503` and `Retry-After`. No request
+  waits longer than `tiles.queue_max_wait_ms`.
+- **Visibility:** `/status` and `/metrics` show the limit, the queries running and the
+  count shed (`planisphere_tile_concurrency_limit`,
+  `planisphere_tile_queries_in_flight`, `planisphere_tiles_total{outcome="shed"}`).
+
+Tile queries slower than `tiles.slow_ms` (default 1000 ms) are logged with the layer and
+z/x/y.
+
+## Admin MCP endpoint
+
+`/mcp` serves [MCP](https://modelcontextprotocol.io) tools built on
+[mcp-host](https://crates.io/crates/mcp-host):
+
+| Tool | |
+|---|---|
+| `status` | the `/status` snapshot: circuit, pool, counters, layers, extensions |
+| `list_layers`, `describe_layer` | layer metadata, including the function's SQL source |
+| `probe_tile` | render one tile through the circuit breaker and time it |
+| `hot_tiles` | the most requested tiles since start (Space-Saving heavy hitters over 64 counters, with each count's possible overestimate): candidates to pre-render or cache longer |
+| `layer_stats` | per-layer tile timings (count, mean, t-digest p50/p95/p99, max) beside `pg_stat_statements` for the same query (calls, mean, stddev, max, rows, cache hit ratio), slowest first. The database side needs `pg_stat_statements`, which RDS preloads by default |
+| `diagnose_layer` | a behavior tree: describe the layer, probe its centre tile at min/mid/max zoom in parallel, then ask the client's model for an assessment (skipped if the client can't sample) |
+| `reload` | rediscover layers and extensions now, and report what changed |
+
+On a loopback listener no token is needed. On any other address planisphere refuses to start
+without a bearer token in `$PLANISPHERE_MCP_TOKEN` (or set `mcp.enabled = false`).
+
+```sh
+claude mcp add --transport http planisphere http://127.0.0.1:8080/mcp
+```
+
+## Ruby
+
+The `planisphere` gem ships the precompiled server for Ruby and Rails apps. Platform gems
+exist for `arm64-darwin` and `aarch64-linux` (glibc 2.17+); other platforms follow.
+Bundler picks the right one.
+
+```ruby
+# Gemfile
+gem 'planisphere'
+```
+
+```sh
+bundle exec planisphere -c config/planisphere.toml serve
+```
+
+`Planisphere.executable` returns the binary's path, for Procfiles or process supervisors.
+On other platforms, install the server with `cargo install planisphere` and set
+`PLANISPHERE_EXECUTABLE` to it.
+
+## Performance
+
+`examples/load.rs` drives keep-alive HTTP/1.1 connections at random tiles of one layer:
+
+```sh
+cargo run --release --example load -- http://127.0.0.1:8080 cities 0-6 32 10
+```
+
+Indicative numbers: an 8-core Apple M1, PostgreSQL 18 in Docker on the same machine, 32
+connections, a 16-connection pool, rate limiting off.
+
+| layer | tile cache | throughput | p50 | p99 |
+|---|---|---|---|---|
+| `cities` (points), z0–6 | off | 17,000 req/s | 1.7 ms | 3.9 ms |
+| `hexbins` (generated polygons), z0–5 | off | 1,000 req/s | 31 ms | 51 ms |
+| `cities` | on | 129,000 req/s | 0.23 ms | 0.53 ms |
+| `hexbins` | on | 93,000 req/s | 0.27 ms | 0.58 ms |
+
+Uncached throughput is whatever the tile functions allow: `hexbins` builds its hexagons per
+request. The MCP `layer_stats` tool shows which layer spends where.
+
+## Development
+
+```sh
+cargo test
+cargo clippy --all-targets
+bundle exec rake test           # gem stub
+bundle exec rake native:build   # platform gem for this machine, into pkg/
+dev/cite-tiles.sh   # OGC API - Tiles conformance suite (Docker, amd64 image)
+dev/cite-wms.sh     # WMS 1.3.0 suite: loads the CITE dataset into schema `cite`, runs it
+```
+
+### Fault injection
+
+A debug build with the `chaos` feature injects faults into tile queries, for hardening
+drills ([rogue-machines](https://crates.io/crates/rogue-machines)). Release builds refuse
+the feature, so it never reaches a binary or a gem.
+
+```sh
+cargo run --features chaos -- -c planisphere.example.toml serve
+```
+
+It adds three MCP tools (MCP must be enabled):
+
+| Tool | |
+|---|---|
+| `chaos_arm` | for `seconds` (at most 3600), make `percent` of one layer's tile queries `raise` (fail like a lost connection), `delay` (run `delay_ms` late, holding their slot) or `garble` (succeed with a body that isn't a tile) |
+| `chaos_disarm` | end one layer's experiment, or all of them |
+| `chaos_status` | live experiments, with what is left of each |
+
+Faults run inside the admission gate and the circuit breaker, so they get the same
+reaction a real fault would: five `raise` failures open the circuit for every layer, and a
+`delay` longer than the queue target makes CoDel shed. A garbled tile is cached like a
+real one until it is evicted or the catalog reloads. `examples/load.rs` drives the traffic.

data/exe/planisphere

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'planisphere'
+
+begin
+  exec(Planisphere.executable, *ARGV)
+rescue Planisphere::UnsupportedPlatform => e
+  warn e.message
+  exit 1
+end

data/lib/planisphere/platforms.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Planisphere
+  # Platform gems published for each release: RubyGems platform => Rust target.
+  # Trimmed to the fleet's hosts while the gem is proven out; the full list
+  # (x86_64 darwin/linux, musl, amd64-freebsd) returns afterwards.
+  PLATFORMS = {
+    'arm64-darwin' => 'aarch64-apple-darwin',
+    'aarch64-linux' => 'aarch64-unknown-linux-gnu'
+  }.freeze
+end

data/lib/planisphere/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Planisphere
+  VERSION = '0.1.2' # x-release-please-version
+end

data/lib/planisphere.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'planisphere/version'
+require_relative 'planisphere/platforms'
+
+# Ruby packaging of the planisphere map server. Platform gems carry the compiled
+# server in libexec/; this module only finds it.
+module Planisphere
+  class UnsupportedPlatform < StandardError; end
+
+  BUNDLED = File.expand_path('../libexec/planisphere', __dir__)
+
+  # Path of the server binary: $PLANISPHERE_EXECUTABLE if set, else the one bundled
+  # in this platform gem.
+  def self.executable(bundled: BUNDLED)
+    override = ENV.fetch('PLANISPHERE_EXECUTABLE', nil)
+    return override if override && !override.empty?
+    return bundled if File.executable?(bundled)
+
+    raise UnsupportedPlatform, <<~MESSAGE.chomp
+      planisphere #{VERSION} has no precompiled binary for #{Gem::Platform.local}.
+      Supported: #{PLATFORMS.keys.join(', ')}.
+      Otherwise install the server with `cargo install planisphere` and set PLANISPHERE_EXECUTABLE.
+    MESSAGE
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: planisphere
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Abdelkader Boudih
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Ships the precompiled planisphere server for use from Ruby and Rails
+  apps.
+email:
+- terminale@gmail.com
+executables:
+- planisphere
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/planisphere
+- lib/planisphere.rb
+- lib/planisphere/platforms.rb
+- lib/planisphere/version.rb
+homepage: https://github.com/seuros/planisphere
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/seuros/planisphere
+  source_code_uri: https://github.com/seuros/planisphere
+  changelog_uri: https://github.com/seuros/planisphere/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'Headless PostGIS map server: vector tiles, OGC API Tiles and WMS'
+test_files: []