Files
meshcore-analyzer/cmd/server/planner_api.go
T
11eb72f578 feat(planner): Coverage tab, reach of a candidate repeater site (#2406)
The repeater planner (#2391) gets a fourth tab, **Coverage**: put a
marker where you are thinking of placing a repeater, set its antenna
height, and see on the map who would hear it. It answers the siting
question "what does a repeater reach if we put it here", with two
layers: handheld users and other repeaters.

## What it shows

- **Users layer:** the chance that a handheld at 1.5 m hears the site,
in 4 bands (10-25%, 25-50%, 50-75%, 75% and up; below 10% is not
painted). The chance comes from a distance curve `P(d) = 1 / (1 +
exp((ln d - ln d50) / slope))`, fitted on drive-test receptions of 41
Belgian repeaters (d50 2.7 km, slope 0.30). Terrain only lowers a cell
by 2 bands where a 1.5 m receiver sits deeper than 1 first-Fresnel
radius under the terrain (`cmd/server/planner_viewshed.go:19-21`).
Antenna height does not change the curve: in the drive tests, handheld
reach barely changed between 1, 7 and 15 m. The panel says so in one
line.
- **Repeaters layer:** first-Fresnel clearance from the site to every
cell, for a receiver at "Repeaters at" height (default
`planner.existingAntennaM`). 3 classes: line of sight (clearance 0% or
more), slightly blocked (-20% to 0%), blocked (not painted). Every known
repeater within range gets its link computed with the existing planner
link code, a dot in its class colour, a line for line of sight and
slightly blocked, and an entry in a list.
- **Compute button:** changing site, height or range moves the marker
and updates the URL hash right away, and dims an existing result with an
"Outdated" note. Only "Compute coverage" starts a job. A shared link
that carries a site computes once on open. The planner has 1 heavy-job
slot shared with Area and allows 6 jobs per minute per IP, so
recomputing on every change would burn both.

State is in the hash:
`#/tools/planner?mode=coverage&site=51.06,4.41&h=10&rx=5&range=30&layer=repeaters`.

This builds on the repeater planner @zfouts wrote in #2391: the terrain
tiles, the first-Fresnel analysis, the link code, the job protocol and
the Area module pattern are all reused here. Thanks for that work, it
made this tab a small addition instead of a new subsystem.

## Why the Repeaters classes are not the route LOS verdicts

The route verdicts (clear 100%+, clear60 60%+, marginal 0%+, blocked)
almost never show on Shuttle Radar Topography Mission (SRTM) terrain at
mast heights. At 10 m / 5 m, 30 km around Mechelen, 109 of 70,980 cells
reach clear60 or clear. SRTM includes trees and roofs, so the line
between 2 masts rarely clears 60% of the Fresnel zone.

I checked the clearance against one Belgian repeater (28 m, receivers at
5 m) and the repeaters live data shows it actually hears:

| Distance | Heard, clearance >= 0 | Heard, clearance < 0 |
|---|---|---|
| 0-10 km | 9 of 11 | none in range |
| 10-20 km | 3 of 4 | 1 of 8 |
| 20-30 km | 0 of 6 | 3 of 35 |
| 30-60 km | 1 of 2 | 0 of 84 |

Every link heard within 16 km had a clearance between 2% and 54%, so
"marginal" is where working links live. The map classes follow that
(`repeaterClass`, `cmd/server/planner_viewshed.go:75-89`). Chain, Relay
and Area keep the shared verdicts; `losVerdict` is unchanged. This rests
on 17 heard links from 1 repeater, which is why the -20% band is narrow
and the panel says line of sight stops being enough beyond about 20 km.

## Server

- `GET /api/planner/viewshed?site=&h=&rx=&range=`
(`cmd/server/planner_api.go:603`, route `cmd/server/routes.go:393`).
Same job protocol, result cache, rate limits and opt-in as the other
planner endpoints: 404 while `planner.enabled` is false.
- One byte per cell: low nibble Users class 1-5, high nibble Repeaters
class 1-3, 0 for no data. The grid is about 300 x 300 at every range:
0.2 km cells up to 30 km, `range/150` above (`planner_viewshed.go:47`).
- Links skip rooms, stale repeaters and a repeater within 100 m of the
site (that is the site itself). They carry no `elev_m` profile.
- `truncated` is true only when the 300-node cap may have dropped a
repeater within range (`viewshedTruncated`, `planner_api.go:694`).
- Tile cap: `Viewshed` in the planner tile limits, sized from the
largest offered range (60 km).
- New config: `planner.userReach.{d50Km,slope}` with a `_comment` in
`config.example.json`. Bounds 0.2-50 km and 0.05-2.
- No writes, no new `map[string]interface{}`; response types
`PlannerViewshedResponse/Params/Link` in `planner_types.go`.

## Frontend

- `public/planner-coverage.js` + `.css`, mounted like `planner-area.js`.
`planner.js` gets a `MODULES` table (`public/planner.js:31`) so Area and
Coverage share one enter/leave path.
- Canvas raster in an `L.imageOverlay`; the layer switch repaints
locally without a new request. Requests go through `fetchJob` / `CSApi`.
- Colours are CSS variables `--pl-cov-user-2..5` and `--pl-cov-rep-1..3`
in `:root` and both dark blocks of `style.css`; the Repeaters ones point
at `--status-*`, so a theme that changes those changes the map.

## Performance

The job is opt-in and runs in the existing planner job slot, never in a
hot path. Measured on real SRTM tiles, local build, 304 Belgian
repeaters:

| Site | Range | Mast | Job time |
|---|---|---|---|
| Maasvallei (hilly) | 30 km | 10 m | 2.07 s |
| Maasvallei | 30 km | 30 m | 2.57 s |
| Maasvallei | 60 km | 10 m | 3.98 s |
| Mechelen (flat) | 30 km | 10 m | 2.61 s |

On a staging instance (ARM64, cold tile cache) a 30 km job took 6.8 s
including the tile downloads. Response size at 60 km with 115 links:
239,942 bytes with link elevation profiles, 149,984 without (what this
PR ships). `BenchmarkViewshedMaxLeg` covers the 60 km worst case on a
synthetic terrain view.

## Verification

- Go: 26 viewshed tests and benchmarks in `planner_viewshed_test.go`,
`planner_api_test.go`, `planner_config_test.go` and
`planner_tiles_test.go`, among them: flat terrain equals the plain curve
and `analyzeLOS`, a ridge shadows only its far side, missing terrain is
"no data", the `truncated` rule (proven to fail on the old rule), links
without `elev_m`, the repeater at the site left out. `go test ./...` in
`cmd/server` passes.
- Frontend: `tests/unit/test-planner-coverage.js` (23 tests, in
`test-all.sh`): grid decode, class-to-colour mapping, unpainted classes,
hash round trip, no fetch on parameter change, 1 fetch per click,
deep-link autorun once, stale responses ignored, link classes at the
boundaries, escaped repeater names.
- E2E: 5 Coverage cases in `tests/e2e/test-planner-e2e.js` (stubbed
viewshed): click and compute, layer switch without a request, outdated
then recompute, deep link, leaving the tab removes the overlay. Planner
E2E 25/25 locally.
- eslint 0 errors. Browser: light and dark theme, Users and Repeaters on
flat, hilly and coastal sites, deep links, no console errors; also on a
staging instance with live data.

## Not in this PR

- The `--pl-cov-*` colours are not in the customizer's `THEME_CSS_MAP`
yet. They follow `--status-*` for the Repeaters layer; the Users colours
need their own entries (AGENTS.md rule 8, later milestone).
- In Flanders the Users layer is close to a circle: 0.3% of cells differ
from the plain curve around Mechelen, 42% in the Maasvallei, 64% in the
Ardennes. The terrain correction is untested in hilly areas, the drive
tests had no repeater there.
- The Repeaters calibration uses 1 repeater. Other operators with drive
tests or neighbour data can tighten it.
- A link's class comes from `clearance_pct`, rounded to 0.1%, while the
grid uses the raw clearance: within 0.05% of a bound a link can land 1
class off the cell under it. List, line and dot always agree with each
other.
- An OS dark-mode switch without the theme toggle does not repaint the
overlay until the next compute, the same as the planner's tile layer.

---------

Co-authored-by: zfouts <zachary.fouts@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 23:19:49 +01:00

1736 lines
56 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package main
// /api/planner/* — the repeater planner's public endpoints. Wire types,
// constants and the 200/202 job protocol are in planner_types.go.
//
// Abuse model. Every request is quantised before anything else happens
// (points to 0.001°, coverage boxes outward to a 0.05° grid, antenna heights
// to 1 m, ranges to a fixed set), so the cache-key space is small and compute
// only ever sees quantised values. Work runs as background jobs, one per
// key: a request waits at most plannerFastWait for its job and otherwise gets
// 202 + PlannerJobStatus to re-poll. Starting a job costs the client a per-IP
// token, plus one token per tile download its terrain view would start from
// the terrain budget it shares with route LOS, and the server a global
// token; cache hits and polls of a live job are free. Compute is kept away
// from the live app by slot semaphores (coverage + viewshed 1, relay + profile 2), caps
// on live and queued jobs, per-stage timeouts, and cancellation of any job
// nobody has polled for plannerAbandonAfter.
//
// Invariants:
// - At most one live job per key. A successful job caches its result before
// it leaves p.jobs (both under p.mu), so no request can see neither and
// start a duplicate.
// - Every job, however it ends (result, error, panic, cancel), gives back
// its slot, leaves p.jobs and the queue count, and closes done once.
// - A job loads its terrain before it takes a compute slot, so a download
// never holds up jobs whose terrain is already here. It counts as queued
// from creation until it holds the slot.
// - A key whose job failed (anything but being abandoned or shut down) is
// answered 503 for plannerFailedFor without a new job or a token, so a
// query that times out or crashes cannot be replayed into the compute
// slot.
// - Node data is read outside the store's long-held locks: the node list
// is the store's shared cache (read only), LastHeardMap holds the read
// lock for one map lookup per pubkey, edges are copied under the graph's
// read lock. Nothing /api/nodes hides (blacklist, hidden names) reaches
// a response, a geo check or a cache key.
import (
"cmp"
"context"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"log"
"math"
"net/http"
"net/url"
"runtime/debug"
"slices"
"sort"
"strconv"
"strings"
"sync"
"sync/atomic"
"time"
)
const (
plannerCacheControl = "public, max-age=300"
plannerMaxRawQuery = 512
plannerCoordScale = 1000.0 // points quantised to 0.001°
plannerGridPerDeg = 20 // coverage boxes snapped to 0.05°
plannerGridEps = 1e-9 // in grid cells: a value on a grid line stays there
plannerCoverageMinLat = -56.0 // SRTM coverage
plannerCoverageMaxLat = 60.0
plannerMinAntennaM = 1.0
plannerMaxAntennaM = 100.0
plannerDefaultSites = 3
plannerProfilePadDeg = 0.01 // covers the great-circle bulge of a 100 km leg (plannerProfilePad)
plannerRelayPadFrac = 0.3 // relay corridor: A,B ± max(0.3·D, 2 km)
plannerRelayPadMinKm = 2.0
plannerMinLegTiles = 6 // profile/relay tile caps never go below this
plannerAreaNodeKm = 10.0 // coverage needs a repeater/room within bbox + this
// plannerObservedMinScore is the Score×Confidence an observed neighbor
// edge needs to count as a backbone link (same floor as the neighbor
// graph view's default minScore).
plannerObservedMinScore = 0.1
plannerKnownTTL = 60 * time.Second
plannerResultTTL = 10 * time.Minute
plannerCovCacheItems = 128
plannerCovCacheBytes = 32 << 20
plannerCheapCacheItems = 1024
plannerCheapCacheBytes = 32 << 20
plannerCovSlots = 1
plannerCheapSlots = 2
plannerMaxQueuedCoverage = 4
plannerMaxLiveJobs = 8
plannerIPJobsPerMin = 6
plannerGlobalJobsPerMin = 30
plannerFullRetryS = 5
plannerFastWait = 1500 * time.Millisecond
plannerTerrainTimeout = 60 * time.Second
plannerComputeTimeout = 20 * time.Second
plannerAbandonAfter = 15 * time.Second
plannerBusyFor = 30 * time.Second
plannerFailedFor = 5 * time.Minute
plannerWatchEvery = time.Second
)
// Endpoints, as they appear in cache keys and log lines.
const (
plannerProfile = "profile"
plannerRelay = "relay"
plannerCoverage = "coverage"
plannerViewshed = "viewshed"
)
// 400 codes the UI matches on (leg errors use the first three too).
// area_too_large: a coverage box side is over the size limit.
// too_many_tiles: the request's terrain view spans more 1° tiles than its
// endpoint's cap (plannerTileLimits).
const (
plannerErrTooLong = "too_long"
plannerErrOutOfArea = "out_of_area"
plannerErrNoTerrain = "no_terrain"
plannerErrAreaTooLarge = "area_too_large"
plannerErrTooManyTiles = "too_many_tiles"
plannerErrNoNodes = "no_nodes_in_area"
)
var (
errPlannerAbandoned = errors.New("planner: job not polled")
errPlannerClosed = errors.New("planner: shutting down")
errPlannerPanic = errors.New("planner: job panicked")
)
// Answers for a key that failed recently.
const (
plannerMsgTerrainBusy = "terrain busy"
plannerMsgFailedRecent = "planner job failed recently"
)
// ─── Data the planner reads ─────────────────────────────────────────────────
// plannerData is everything the planner reads from the rest of the server.
// serverPlannerData is the real one; tests inject fixed data.
type plannerData interface {
// nodes is the node list. It is shared with other readers: never modify it.
nodes() []nodeInfo
// lastHeard is the certain last-heard time of each pubkey that has one.
lastHeard(pubkeys []string) map[string]time.Time
// edges is a private copy of the neighbor edges between pubkeys.
edges(pubkeys []string) []NeighborEdge
// filter is what /api/nodes hides, plus each role's silent window.
filter() plannerNodeFilter
// filterGen changes whenever the hiding rules change.
filterGen() string
}
type serverPlannerData struct{ s *Server }
func (d serverPlannerData) nodes() []nodeInfo {
if d.s == nil || d.s.store == nil {
return nil
}
ns, _ := d.s.store.getCachedNodesAndPM()
return ns
}
func (d serverPlannerData) lastHeard(pubkeys []string) map[string]time.Time {
if d.s == nil || d.s.store == nil || len(pubkeys) == 0 {
return nil
}
m, _ := d.s.store.LastHeardMap(pubkeys)
return m
}
func (d serverPlannerData) edges(pubkeys []string) []NeighborEdge {
if d.s == nil || len(pubkeys) == 0 {
return nil
}
return d.s.getNeighborGraph().snapshotEdgesAmong(pubkeys)
}
func (d serverPlannerData) filter() plannerNodeFilter {
var cfg *Config
if d.s != nil {
cfg = d.s.cfg
}
if cfg == nil {
return plannerNodeFilter{}
}
h := cfg.GetHealthThresholds()
return plannerNodeFilter{
// Exactly what /api/nodes hides (node_visibility.go): a node the
// operator filtered out of the API must not surface through the
// planner, and a foreign one it shows is usable.
Visible: d.s.visibleNodeInfo(),
SilentAfter: func(role string) time.Duration {
_, silentMs := h.GetHealthMs(role)
return time.Duration(silentMs) * time.Millisecond
},
}
}
func (d serverPlannerData) filterGen() string { return d.s.nodeVisibilityGen() }
// ─── Service ────────────────────────────────────────────────────────────────
// plannerService holds terrain, caches, limiters and the job runner.
type plannerService struct {
cfg PlannerConfig // resolved
freqMHz float64 // radio defaults from the los block, like the LOS tool
kFactor float64
tiles plannerTileLimits
source string // terrain attribution in every response (terrainSourceName)
src terrainSource
data plannerData
coverage func(ctx context.Context, v terrainView, in planInputs, progress func(float64)) (PlannerPlanResponse, error)
relay func(ctx context.Context, v terrainView, nodes []plannerNode, p PlannerRelayParams, progress func(float64)) (PlannerRelayResponse, error)
now func() time.Time
// limit charges the client for each job it starts; global caps new jobs
// for everyone. downloads charges the client per tile download a job's
// view starts: the budget route LOS shares (newTerrainServices), else
// this planner's own.
limit clientLimiter
downloads *clientLimiter
global *rateLimiter
// Timings (fields so tests can shorten them).
fastWait, terrainTimeout, computeTimeout time.Duration
abandonAfter, busyFor, failedFor time.Duration
watchEvery time.Duration
knownMu sync.Mutex // one rebuild at a time
known atomic.Pointer[plannerKnown]
covCache, cheapCache *plannerLRU
covSlots, cheapSlots chan struct{}
epoch time.Time // origin of plannerJob.polledAt
ctx context.Context // parent of every job; Close cancels it
cancel context.CancelCauseFunc
wg sync.WaitGroup
mu sync.Mutex
closed bool
jobs map[string]*plannerJob
covQueued int // coverage jobs not yet holding a slot
recent map[string]plannerRecent // keys answered 503 without a new job
}
// plannerRecent is a key's recent failure: requests for it get msg until
// the entry lapses.
type plannerRecent struct {
until time.Time
msg string
}
// newPlannerService builds the service from the resolved config over terrain,
// the SRTM source it shares with route LOS (newTerrainServices); nil builds a
// private default one sized for this planner (tests). It starts no
// goroutine; each job brings its own and Close stops them.
func newPlannerService(cfg PlannerConfig, s *Server, terrain *srtmSource) *plannerService {
rc, _ := cfg.resolved()
if terrain == nil {
terrain = newSRTMSource(TerrainConfig{}, rc.tileLimits().max())
}
var los *LOSConfig
var trusted []string
if s != nil && s.cfg != nil {
los = s.cfg.LOS
trusted = s.cfg.WSTrustedProxies()
}
radio, _ := los.resolved()
ctx, cancel := context.WithCancelCause(context.Background())
return &plannerService{
cfg: rc,
freqMHz: radio.FrequencyMHz,
kFactor: radio.KFactor,
tiles: rc.tileLimits(),
source: terrain.source,
src: terrain,
data: serverPlannerData{s},
coverage: runCoveragePlan,
relay: runRelaySearch,
now: time.Now,
limit: clientLimiter{
ipr: &wsLimiter{state: map[string]*wsIPState{},
trustedProxies: parseCIDRList(trusted, "webSocket.trustedProxies")},
rl: newRateLimiter(plannerIPJobsPerMin, time.Minute),
tag: "planner", what: "planner",
},
downloads: newTerrainClientLimiter(trusted, terrain.maxTiles),
global: newRateLimiter(plannerGlobalJobsPerMin, time.Minute),
fastWait: plannerFastWait,
terrainTimeout: plannerTerrainTimeout,
computeTimeout: plannerComputeTimeout,
abandonAfter: plannerAbandonAfter,
busyFor: plannerBusyFor,
failedFor: plannerFailedFor,
watchEvery: plannerWatchEvery,
covCache: newPlannerLRU(plannerCovCacheItems, plannerCovCacheBytes, plannerResultTTL),
cheapCache: newPlannerLRU(plannerCheapCacheItems, plannerCheapCacheBytes, plannerResultTTL),
covSlots: make(chan struct{}, plannerCovSlots),
cheapSlots: make(chan struct{}, plannerCheapSlots),
epoch: time.Now(),
ctx: ctx,
cancel: cancel,
jobs: map[string]*plannerJob{},
recent: map[string]plannerRecent{},
}
}
// Close cancels every job, refuses new ones and waits for the job
// goroutines to return.
func (p *plannerService) Close() {
p.mu.Lock()
p.closed = true
p.mu.Unlock()
p.cancel(errPlannerClosed)
p.wg.Wait()
}
func (s *Server) plannerDisabled(w http.ResponseWriter) bool {
if !s.cfg.Planner.enabled() || s.planner == nil {
writeError(w, http.StatusNotFound, "planner disabled")
return true
}
return false
}
func (s *Server) handlePlannerProfile(w http.ResponseWriter, r *http.Request) {
if s.plannerDisabled(w) {
return
}
s.planner.handleProfile(w, r)
}
func (s *Server) handlePlannerRelay(w http.ResponseWriter, r *http.Request) {
if s.plannerDisabled(w) {
return
}
s.planner.handleRelay(w, r)
}
func (s *Server) handlePlannerCoverage(w http.ResponseWriter, r *http.Request) {
if s.plannerDisabled(w) {
return
}
s.planner.handleCoverage(w, r)
}
func (s *Server) handlePlannerViewshed(w http.ResponseWriter, r *http.Request) {
if s.plannerDisabled(w) {
return
}
s.planner.handleViewshed(w, r)
}
// ─── /api/planner/profile ───────────────────────────────────────────────────
func (p *plannerService) handleProfile(w http.ResponseWriter, r *http.Request) {
q, rej := plannerParseQuery(r.URL.RawQuery, "pts")
if rej != nil {
rej.write(w)
return
}
raw, ok := q["pts"]
if !ok {
plannerBadRequest(w, "pts required")
return
}
pts, msg := plannerParsePts(raw)
if msg != "" {
plannerBadRequest(w, msg)
return
}
known := p.knownSet()
far := make([]bool, len(pts))
for i, pt := range pts {
far[i] = !known.near(pt)
}
legs := make([]PlannerProfileLeg, len(pts)-1)
var key strings.Builder
key.WriteString(plannerProfile)
for _, pt := range pts {
fmt.Fprintf(&key, "|%d,%d", plannerMilli(pt.Lat), plannerMilli(pt.Lon))
}
key.WriteByte('|')
var bb geoBBox
valid := 0
for i := range legs {
d := geoDistKm(pts[i], pts[i+1])
legs[i].DistanceKm = losRound(d, 1000)
switch {
case d > p.cfg.MaxLegKm:
legs[i].Error = plannerErrTooLong
key.WriteByte('L')
case far[i] || far[i+1]:
legs[i].Error = plannerErrOutOfArea
key.WriteByte('A')
default:
key.WriteByte('-')
if valid == 0 {
bb = geoBBox{S: pts[i].Lat, W: pts[i].Lon, N: pts[i].Lat, E: pts[i].Lon}
}
bb = plannerBBoxAdd(plannerBBoxAdd(bb, pts[i]), pts[i+1])
valid++
}
}
if valid == 0 {
// Nothing to sample: the answer is fully decided here, no job.
body, err := plannerEncode(PlannerProfileResponse{Source: p.source, Legs: legs})
if err != nil {
writeError(w, http.StatusInternalServerError, "planner failed")
return
}
writePlannerResult(w, body)
return
}
bb = plannerProfileView(bb, plannerProfilePad(p.cfg.MaxLegKm))
if p.src.TileCount(bb) > p.tiles.Profile {
plannerBadRequest(w, plannerErrTooManyTiles)
return
}
p.serve(w, r, plannerJobSpec{
endpoint: plannerProfile,
key: key.String(),
view: bb,
compute: func(ctx context.Context, v terrainView, progress func(float64)) (any, error) {
res, err := planProfileLegs(ctx, v, pts, legs, progress)
res.Source = p.source
return res, err
},
})
}
// plannerProfilePad is the profile view's margin in degrees for legs up to
// maxLegKm. A great circle bulges poleward of its endpoints by about
// tan(lat)·(d/R)²/8, so the 0.01° that covers a 100 km leg (0.003° at 60°,
// 0.01° at 80°) scales with the square of the leg.
func plannerProfilePad(maxLegKm float64) float64 {
scale := maxLegKm / defaultPlannerMaxLegKm
return plannerProfilePadDeg * math.Max(1, scale*scale)
}
// plannerProfileView is the terrain a profile over legs (the bbox of its
// valid legs' endpoints) reads: grown by padDeg on every side for the
// great-circle bulge.
func plannerProfileView(legs geoBBox, padDeg float64) geoBBox {
return geoBBox{S: legs.S - padDeg, W: legs.W - padDeg, N: legs.N + padDeg, E: legs.E + padDeg}
}
// planProfileLegs samples every leg without an error (sampleLegProfile, as
// route LOS does); legs is the request's pre-checked template and is not
// modified. A leg with any sample on a tile without data is no_terrain
// (terrain has no elevation there, never a 0 m valley), and the response
// carries the terrain warning. The caller sets Source.
func planProfileLegs(ctx context.Context, v terrainView, pts []geoPoint, legs []PlannerProfileLeg,
progress func(float64)) (PlannerProfileResponse, error) {
out := PlannerProfileResponse{Legs: slices.Clone(legs)}
if w := plannerTerrainWarning(v); w != "" {
out.Warnings = []string{w}
}
for i := range out.Legs {
if err := ctx.Err(); err != nil {
return PlannerProfileResponse{}, err
}
if leg := &out.Legs[i]; leg.Error == "" {
if elev, ok := sampleLegProfile(v, pts[i], pts[i+1]); ok {
leg.ElevM = elev
} else {
leg.Error = plannerErrNoTerrain
}
}
progress(float64(i+1) / float64(len(out.Legs)))
}
return out, nil
}
// plannerTerrainWarning is the warning to show when some of v's tiles have
// no data, which every endpoint skips; "" when it has none or cannot tell.
func plannerTerrainWarning(v terrainView) string {
tc, ok := v.(terrainCoverage)
if !ok {
return ""
}
missing, total := tc.MissingTiles()
if missing == 0 {
return ""
}
return fmt.Sprintf("Terrain missing for %d of %d tiles (open sea or unavailable): sites and links there were skipped",
missing, total)
}
// ─── /api/planner/relay ─────────────────────────────────────────────────────
func (p *plannerService) handleRelay(w http.ResponseWriter, r *http.Request) {
q, rej := plannerParseQuery(r.URL.RawQuery, "a", "b", "ha", "hb", "hr", "range")
if rej != nil {
rej.write(w)
return
}
var ends [2]geoPoint
for i, k := range [2]string{"a", "b"} {
raw, ok := q[k]
if !ok {
plannerBadRequest(w, k+" required")
return
}
pt, ok := plannerParsePoint(raw)
if !ok {
plannerBadRequest(w, k+" must be lat,lon within range")
return
}
ends[i] = pt
}
a, b := ends[0], ends[1]
var heights [3]float64
for i, k := range [3]string{"ha", "hb", "hr"} {
h, ok := plannerOptHeight(q, k, p.cfg.NewAntennaM)
if !ok {
plannerBadRequest(w, k+" must be a number of metres")
return
}
heights[i] = h
}
rangeKm, ok := plannerOptRange(q, p.cfg.DefaultRangeKm, p.cfg.rangesKm())
if !ok {
plannerBadRequest(w, plannerRangeMsg(p.cfg.rangesKm()))
return
}
d := geoDistKm(a, b)
if d > p.cfg.MaxLegKm {
plannerBadRequest(w, plannerErrTooLong)
return
}
known := p.knownSet()
if !known.near(a) || !known.near(b) {
plannerBadRequest(w, plannerErrOutOfArea)
return
}
view := plannerRelayView(a, b)
if p.src.TileCount(view) > p.tiles.Relay {
plannerBadRequest(w, plannerErrTooManyTiles)
return
}
params := PlannerRelayParams{
A: geoPointJSON{Lat: a.Lat, Lon: a.Lon},
B: geoPointJSON{Lat: b.Lat, Lon: b.Lon},
AntennaAM: heights[0],
AntennaBM: heights[1],
RelayAntennaM: heights[2],
ExistingAntennaM: p.cfg.ExistingAntennaM,
RangeKm: rangeKm,
FrequencyMHz: p.freqMHz,
KFactor: p.kFactor,
}
_, fp := known.scan(view, 0, 0)
key := fmt.Sprintf("%s|%d,%d|%d,%d|%g,%g,%g|%g|%s|%s", plannerRelay,
plannerMilli(a.Lat), plannerMilli(a.Lon), plannerMilli(b.Lat), plannerMilli(b.Lon),
heights[0], heights[1], heights[2], rangeKm, fp, known.gen)
p.serve(w, r, plannerJobSpec{
endpoint: plannerRelay,
key: key,
view: view,
compute: func(ctx context.Context, v terrainView, progress func(float64)) (any, error) {
nodes, _ := p.snapshotNodes(view, 0, p.now())
res, err := p.relay(ctx, v, nodes, params, progress)
if err != nil {
return nil, err
}
res.Source = p.source
if res.Params == (PlannerRelayParams{}) {
res.Params = params
}
res.Existing = plannerNonNil(res.Existing)
res.Open = plannerNonNil(res.Open)
if w := plannerTerrainWarning(v); w != "" {
res.Warnings = append(res.Warnings, w)
}
res.Warnings = plannerNonNil(res.Warnings)
return res, nil
},
})
}
// plannerRelayPad is the corridor margin around a leg of dKm.
func plannerRelayPad(dKm float64) float64 {
return math.Max(plannerRelayPadFrac*dKm, plannerRelayPadMinKm)
}
// plannerRelayView is the terrain a relay search for a→b reads: the
// endpoints' bbox grown by plannerRelayPad on every side.
func plannerRelayView(a, b geoPoint) geoBBox {
ends := plannerBBoxAdd(geoBBox{S: a.Lat, W: a.Lon, N: a.Lat, E: a.Lon}, b)
return plannerExpandBBox(ends, plannerRelayPad(geoDistKm(a, b)))
}
// ─── /api/planner/viewshed ──────────────────────────────────────────────────
func (p *plannerService) handleViewshed(w http.ResponseWriter, r *http.Request) {
q, rej := plannerParseQuery(r.URL.RawQuery, "site", "h", "rx", "range")
if rej != nil {
rej.write(w)
return
}
raw, ok := q["site"]
if !ok {
plannerBadRequest(w, "site required")
return
}
site, ok := plannerParsePoint(raw)
if !ok {
plannerBadRequest(w, "site must be lat,lon within range")
return
}
h, ok := plannerOptHeight(q, "h", p.cfg.NewAntennaM)
if !ok {
plannerBadRequest(w, "h must be a number of metres")
return
}
rx, ok := plannerOptHeight(q, "rx", p.cfg.ExistingAntennaM)
if !ok {
plannerBadRequest(w, "rx must be a number of metres")
return
}
rangeKm, ok := plannerOptRange(q, p.cfg.DefaultRangeKm, p.cfg.rangesKm())
if !ok {
plannerBadRequest(w, plannerRangeMsg(p.cfg.rangesKm()))
return
}
known := p.knownSet()
if !known.near(site) {
plannerBadRequest(w, plannerErrOutOfArea)
return
}
view := viewshedBBox(site, rangeKm)
if p.src.TileCount(view) > p.tiles.Viewshed {
plannerBadRequest(w, plannerErrTooManyTiles)
return
}
reach := *p.cfg.UserReach
params := PlannerViewshedParams{
Site: geoPointJSON{Lat: site.Lat, Lon: site.Lon},
AntennaM: h,
RxAntennaM: rx,
RangeKm: rangeKm,
FrequencyMHz: p.freqMHz,
KFactor: p.kFactor,
UserReach: PlannerViewshedUserReach{D50Km: reach.D50Km, Slope: reach.Slope},
}
_, fp := known.scan(view, 0, 0)
key := fmt.Sprintf("%s|%d,%d|%g,%g|%g|%g,%g|%s|%s", plannerViewshed,
plannerMilli(site.Lat), plannerMilli(site.Lon), h, rx, rangeKm, reach.D50Km, reach.Slope, fp, known.gen)
p.serve(w, r, plannerJobSpec{
endpoint: plannerViewshed,
key: key,
view: view,
compute: func(ctx context.Context, v terrainView, progress func(float64)) (any, error) {
g, err := computeViewshed(ctx, v, viewshedParams{
Site: site, SiteM: h, RxM: rx, RangeKm: rangeKm,
FreqMHz: p.freqMHz, KFactor: p.kFactor, Reach: reach,
}, progress)
if err != nil {
return nil, err
}
nodes, truncated := p.snapshotNodes(view, 0, p.now())
res := PlannerViewshedResponse{
Source: p.source,
Params: params,
BBox: [4]float64{g.BBox.S, g.BBox.W, g.BBox.N, g.BBox.E},
Rows: g.Rows,
Cols: g.Cols,
CellKm: g.CellKm,
Cells: base64.StdEncoding.EncodeToString(g.Cells),
Links: viewshedLinks(v, site, nodes, rangeKm, losParams{FreqMHz: p.freqMHz, KFactor: p.kFactor}, h, rx),
Warnings: []string{},
Truncated: viewshedTruncated(site, nodes, rangeKm, truncated),
}
if w := plannerTerrainWarning(v); w != "" {
res.Warnings = append(res.Warnings, w)
}
return res, nil
},
})
}
// viewshedTruncated reports a node-cap cut that may have cost a link. The cap
// keeps the nodes nearest the site, so everything dropped lies at least as far
// as the farthest kept one: when that is already beyond rangeKm (the square
// view's corners), no in-range repeater was lost.
func viewshedTruncated(site geoPoint, kept []plannerNode, rangeKm float64, capped bool) bool {
if !capped {
return false
}
var farthest float64
for i := range kept {
farthest = max(farthest, geoDistKm(site, geoPoint{Lat: kept[i].Lat, Lon: kept[i].Lon}))
}
return farthest <= rangeKm
}
// viewshedSelfKm: a repeater this close to the site is the site itself (a
// candidate placed on an existing repeater), not a link to list.
const viewshedSelfKm = 0.1
// viewshedLinks is the site's link to every repeater within rangeKm that
// Relay would offer (not stale, valid position), nearest first (then by
// pubkey), the site at h and the repeater at rx.
func viewshedLinks(v terrainView, site geoPoint, nodes []plannerNode, rangeKm float64, lp losParams, h, rx float64) []PlannerViewshedLink {
type near struct {
n *plannerNode
d float64
}
var in []near
for i := range nodes {
n := &nodes[i]
if n.Role != "repeater" || n.Stale || !planCoordOK(n.Lat, n.Lon) {
continue
}
if d := geoDistKm(site, geoPoint{Lat: n.Lat, Lon: n.Lon}); d >= viewshedSelfKm && d <= rangeKm {
in = append(in, near{n, d})
}
}
slices.SortFunc(in, func(a, b near) int {
if c := cmp.Compare(a.d, b.d); c != 0 {
return c
}
return strings.Compare(a.n.PubKey, b.n.PubKey)
})
out := make([]PlannerViewshedLink, len(in))
for i, e := range in {
pt := geoPoint{Lat: e.n.Lat, Lon: e.n.Lon}
out[i] = PlannerViewshedLink{
PubKey: e.n.PubKey, Name: e.n.Name, Lat: e.n.Lat, Lon: e.n.Lon,
Link: relayLink(v, site, pt, e.d, lp, h, rx, false),
}
}
return out
}
// ─── /api/planner/coverage ──────────────────────────────────────────────────
func (p *plannerService) handleCoverage(w http.ResponseWriter, r *http.Request) {
q, rej := plannerParseQuery(r.URL.RawQuery, "bbox", "sites", "range", "hr", "he", "baseline", "stale")
if rej != nil {
rej.write(w)
return
}
raw, ok := q["bbox"]
if !ok {
plannerBadRequest(w, "bbox required")
return
}
grid, msg := plannerParseGridBox(raw, p.cfg.MaxAreaKm)
if msg != "" {
plannerBadRequest(w, msg)
return
}
sites := plannerDefaultSites
if s, ok := q["sites"]; ok {
n, err := strconv.Atoi(s)
if err != nil || n < 1 || n > plannerMaxSites {
plannerBadRequest(w, fmt.Sprintf("sites must be an integer 1-%d", plannerMaxSites))
return
}
sites = n
}
rangeKm, ok := plannerOptRange(q, p.cfg.DefaultRangeKm, p.cfg.rangesKm())
if !ok {
plannerBadRequest(w, plannerRangeMsg(p.cfg.rangesKm()))
return
}
hr, ok1 := plannerOptHeight(q, "hr", p.cfg.NewAntennaM)
he, ok2 := plannerOptHeight(q, "he", p.cfg.ExistingAntennaM)
if !ok1 || !ok2 {
plannerBadRequest(w, "hr and he must be numbers of metres")
return
}
baseline := "predicted"
if s, ok := q["baseline"]; ok {
if s != "predicted" && s != "observed" {
plannerBadRequest(w, "baseline must be predicted or observed")
return
}
baseline = s
}
stale := false
if s, ok := q["stale"]; ok {
if s != "0" && s != "1" {
plannerBadRequest(w, "stale must be 0 or 1")
return
}
stale = s == "1"
}
area := grid.bbox()
known := p.knownSet()
margin := p.cfg.NodeMarginKm
hasNodes, fp := known.scan(area, plannerAreaNodeKm, margin)
if !hasNodes {
plannerBadRequest(w, plannerErrNoNodes)
return
}
view := plannerExpandBBox(area, margin)
if p.src.TileCount(view) > p.tiles.Coverage {
plannerBadRequest(w, plannerErrTooManyTiles)
return
}
params := PlannerPlanParams{
Sites: sites,
RangeKm: rangeKm,
NewAntennaM: hr,
ExistingAntennaM: he,
Baseline: baseline,
IncludeStale: stale,
FrequencyMHz: p.freqMHz,
KFactor: p.kFactor,
MinClearance: plannerMinClearance,
}
key := fmt.Sprintf("%s|%d,%d,%d,%d|%d|%g|%g,%g|%s|%t|%s|%s", plannerCoverage,
grid.s, grid.w, grid.n, grid.e, sites, rangeKm, hr, he, baseline, stale, fp, known.gen)
p.serve(w, r, plannerJobSpec{
endpoint: plannerCoverage,
key: key,
view: view,
compute: func(ctx context.Context, v terrainView, progress func(float64)) (any, error) {
now := p.now()
nodes, truncated := p.snapshotNodes(area, margin, now)
pubkeys := make([]string, len(nodes))
for i := range nodes {
pubkeys[i] = nodes[i].PubKey
}
observed := observedPlannerEdges(nodes, p.data.edges(pubkeys), now, plannerObservedMinScore)
res, err := p.coverage(ctx, v, planInputs{
Area: area, Nodes: nodes, Observed: observed, Truncated: truncated, Params: params,
}, progress)
if err != nil {
return nil, err
}
if res.Area == (geoBBoxJSON{}) {
res.Area = geoBBoxJSON{S: area.S, W: area.W, N: area.N, E: area.E}
}
if res.Params == (PlannerPlanParams{}) {
res.Params = params
}
res.Source = p.source
if res.ComputedAt.IsZero() {
res.ComputedAt = now.UTC()
}
res.Truncated = res.Truncated || truncated
res.Nodes = plannerNonNil(res.Nodes)
res.Edges = plannerNonNil(res.Edges)
res.Sites = plannerNonNil(res.Sites)
if w := plannerTerrainWarning(v); w != "" {
res.Warnings = append(res.Warnings, w)
}
res.Warnings = plannerNonNil(res.Warnings)
return res, nil
},
})
}
// snapshotNodes selects a job's repeaters/rooms from one read of the node
// cache. Only candidates' pubkeys go to LastHeardMap, keeping its store
// read lock short.
func (p *plannerService) snapshotNodes(area geoBBox, marginKm float64, now time.Time) ([]plannerNode, bool) {
all := p.data.nodes()
outer := plannerExpandBBox(area, marginKm)
var pubkeys []string
for i := range all {
n := &all[i]
if (n.Role == "repeater" || n.Role == "room") && n.HasGPS && plannerBBoxContains(outer, n.Lat, n.Lon) {
pubkeys = append(pubkeys, n.PublicKey)
}
}
return selectPlannerNodes(all, p.data.lastHeard(pubkeys), area, marginKm, p.data.filter(), now)
}
// ─── Parsing ────────────────────────────────────────────────────────────────
// plannerParseQuery applies the checks common to every endpoint: a bounded
// query, only the allowed keys, none repeated.
func plannerParseQuery(raw string, allowed ...string) (map[string]string, *plannerReject) {
if len(raw) > plannerMaxRawQuery {
return nil, &plannerReject{code: http.StatusBadRequest, msg: "query too long"}
}
vals, err := url.ParseQuery(raw)
if err != nil {
return nil, &plannerReject{code: http.StatusBadRequest, msg: "malformed query"}
}
out := make(map[string]string, len(vals))
for k, v := range vals {
if !slices.Contains(allowed, k) {
return nil, &plannerReject{code: http.StatusBadRequest, msg: fmt.Sprintf("unknown parameter %q", k)}
}
if len(v) != 1 {
return nil, &plannerReject{code: http.StatusBadRequest, msg: fmt.Sprintf("duplicate parameter %q", k)}
}
out[k] = v[0]
}
return out, nil
}
// plannerFloat parses a finite float.
func plannerFloat(s string) (float64, bool) {
f, err := strconv.ParseFloat(s, 64)
if err != nil || math.IsNaN(f) || math.IsInf(f, 0) {
return 0, false
}
return f, true
}
// plannerMilli is v in thousandths of a degree, the planner's point quantum.
func plannerMilli(v float64) int64 { return int64(math.Round(v * plannerCoordScale)) }
// plannerLatLon range-checks and quantises one point.
func plannerLatLon(latS, lonS string) (geoPoint, bool) {
lat, ok1 := plannerFloat(latS)
lon, ok2 := plannerFloat(lonS)
if !ok1 || !ok2 || lat < -90 || lat > 90 || lon < -180 || lon > 180 {
return geoPoint{}, false
}
return geoPoint{
Lat: float64(plannerMilli(lat)) / plannerCoordScale,
Lon: float64(plannerMilli(lon)) / plannerCoordScale,
}, true
}
// plannerParsePoint parses "lat,lon".
func plannerParsePoint(raw string) (geoPoint, bool) {
if strings.Count(raw, ",") != 1 {
return geoPoint{}, false
}
la, lo, _ := strings.Cut(raw, ",")
return plannerLatLon(la, lo)
}
// plannerParsePts parses the flat "lat,lon,lat,lon..." list; the second
// return value is a 400 message, empty when valid. Separators are counted
// before splitting, so an oversized list costs no allocation.
func plannerParsePts(raw string) ([]geoPoint, string) {
c := strings.Count(raw, ",")
if c%2 == 0 || c < 3 || c > 2*plannerMaxPoints-1 {
return nil, fmt.Sprintf("pts must hold 2 to %d lat,lon points", plannerMaxPoints)
}
parts := strings.Split(raw, ",")
pts := make([]geoPoint, len(parts)/2)
for i := range pts {
pt, ok := plannerLatLon(parts[2*i], parts[2*i+1])
if !ok {
return nil, "pts contains an invalid or out-of-range number"
}
pts[i] = pt
}
return pts, ""
}
// plannerHeight rounds an antenna height to 1 m and clamps it to 1..100.
func plannerHeight(v float64) float64 {
v = math.Round(v)
if v < plannerMinAntennaM {
return plannerMinAntennaM
}
if v > plannerMaxAntennaM {
return plannerMaxAntennaM
}
return v
}
func plannerOptHeight(q map[string]string, key string, def float64) (float64, bool) {
s, ok := q[key]
if !ok {
return plannerHeight(def), true
}
v, ok := plannerFloat(s)
if !ok {
return 0, false
}
return plannerHeight(v), true
}
// plannerOptRange is the "range" parameter, def when absent; it must be
// one of allowed.
func plannerOptRange(q map[string]string, def float64, allowed []float64) (float64, bool) {
s, ok := q["range"]
if !ok {
return def, true
}
v, ok := plannerFloat(s)
if !ok || !slices.Contains(allowed, v) {
return 0, false
}
return v, true
}
func plannerRangeMsg(allowed []float64) string {
s := make([]string, len(allowed))
for i, r := range allowed {
s[i] = strconv.FormatFloat(r, 'f', -1, 64)
}
return "range must be one of " + strings.Join(s, ",")
}
// plannerGridBox is a coverage area in 0.05° grid cells.
type plannerGridBox struct{ s, w, n, e int }
func (g plannerGridBox) bbox() geoBBox {
return geoBBox{
S: float64(g.s) / plannerGridPerDeg, W: float64(g.w) / plannerGridPerDeg,
N: float64(g.n) / plannerGridPerDeg, E: float64(g.e) / plannerGridPerDeg,
}
}
// plannerParseGridBox parses "s,w,n,e" and snaps it outward to the grid;
// neither side of the snapped box may exceed maxAreaKm. The second return
// value is a 400 message, empty when valid.
func plannerParseGridBox(raw string, maxAreaKm float64) (plannerGridBox, string) {
const bad = "bbox must be s,w,n,e in degrees"
if strings.Count(raw, ",") != 3 {
return plannerGridBox{}, bad
}
parts := strings.Split(raw, ",")
var v [4]float64
for i, s := range parts {
f, ok := plannerFloat(s)
if !ok {
return plannerGridBox{}, bad
}
v[i] = f
}
s, w, n, e := v[0], v[1], v[2], v[3]
if s < -90 || n > 90 || w < -180 || e > 180 {
return plannerGridBox{}, bad
}
if !(s < n) || !(w < e) {
return plannerGridBox{}, "bbox needs south below north and west below east (no antimeridian crossing)"
}
g := plannerGridBox{
s: int(math.Floor(s*plannerGridPerDeg + plannerGridEps)),
w: int(math.Floor(w*plannerGridPerDeg + plannerGridEps)),
n: int(math.Ceil(n*plannerGridPerDeg - plannerGridEps)),
e: int(math.Ceil(e*plannerGridPerDeg - plannerGridEps)),
}
if g.n <= g.s {
g.n = g.s + 1
}
if g.e <= g.w {
g.e = g.w + 1
}
bb := g.bbox()
if bb.S < plannerCoverageMinLat || bb.N > plannerCoverageMaxLat {
return plannerGridBox{}, "bbox must lie within latitudes -56 to 60 (terrain coverage)"
}
hKm := (bb.N - bb.S) * plannerKmPerDeg
wKm := (bb.E - bb.W) * plannerKmPerDeg * math.Cos((bb.S+bb.N)/2*math.Pi/180)
if hKm > maxAreaKm || wKm > maxAreaKm {
return plannerGridBox{}, plannerErrAreaTooLarge
}
return g, ""
}
// plannerBBoxAdd grows bb to include pt.
func plannerBBoxAdd(bb geoBBox, pt geoPoint) geoBBox {
bb.S, bb.N = math.Min(bb.S, pt.Lat), math.Max(bb.N, pt.Lat)
bb.W, bb.E = math.Min(bb.W, pt.Lon), math.Max(bb.E, pt.Lon)
return bb
}
// plannerNonNil turns a nil slice into an empty one so it encodes as [].
func plannerNonNil[T any](s []T) []T {
if s == nil {
return []T{}
}
return s
}
// ─── Terrain tile caps ──────────────────────────────────────────────────────
// plannerTileLimits is the most 1° terrain tiles one request's view may span,
// per endpoint. Each is the worst case of the largest request the size
// limits accept anywhere in the SRTM latitude band, so such a request is
// never refused for its tiles. A view over its cap (a profile chain of many
// long legs, a leg beyond the band) is too_many_tiles.
type plannerTileLimits struct{ Profile, Relay, Coverage, Viewshed int }
// max is the most tiles one view may need: what the terrain source accepts
// in one View.
func (l plannerTileLimits) max() int { return max(l.Profile, l.Relay, l.Coverage, l.Viewshed) }
// plannerTileCaps derives the caps from the size limits.
//
// - Coverage: the parser checks the snapped box, so its sides are at most
// maxAreaKm (the width at the box's middle latitude) and its edges within
// the band; the view adds nodeMarginKm on every side. Every point of the
// view lies within the band's edge plus the margin (plus one grid cell,
// to spare), and its extent is at most maxAreaKm + 2·nodeMarginKm.
// - Relay: A and B are at most maxLegKm apart and the corridor adds
// plannerRelayPad of that on every side, so its extent is at most
// maxLegKm + 2·plannerRelayPad(maxLegKm), with A and B in the band.
// - Profile: one leg's view (its pad is far below the relay corridor's)
// fits the relay's; longer chains may not.
// - Viewshed: the site ± its range, the site in the band. The cap uses
// the largest range a request can ask for, the largest of
// plannerRangesKm within maxLegKm (60 km at most), not maxLegKm itself:
// 2·maxLegKm would raise max(), and so every view's memory and the
// download budgets, for views no request can make.
//
// Profile and relay never go below plannerMinLegTiles.
func plannerTileCaps(maxAreaKm, nodeMarginKm, maxLegKm float64) plannerTileLimits {
band := math.Max(plannerCoverageMaxLat, -plannerCoverageMinLat)
cov := plannerWorstCaseTiles(maxAreaKm+2*nodeMarginKm,
band+nodeMarginKm/plannerKmPerDeg+1.0/plannerGridPerDeg)
pad := plannerRelayPad(maxLegKm)
leg := max(plannerWorstCaseTiles(maxLegKm+2*pad, band+pad/plannerKmPerDeg), plannerMinLegTiles)
ranges := PlannerConfig{MaxLegKm: maxLegKm}.rangesKm()
rv := ranges[len(ranges)-1]
vs := plannerWorstCaseTiles(2*rv, band+rv/plannerKmPerDeg)
return plannerTileLimits{Profile: leg, Relay: leg, Coverage: cov, Viewshed: vs}
}
// plannerWorstCaseTiles is the most 1° SRTM tiles a view can span when it
// extends at most sideKm north-south and east-west and no point of it lies
// beyond maxAbsLat. A span of x degrees touches at most ceil(x)+1 tiles,
// when it starts just short of a degree line; the 1e-9° keeps a span that
// rounding nudged past a whole number from being counted one short.
func plannerWorstCaseTiles(sideKm, maxAbsLat float64) int {
lat := math.Ceil(sideKm/plannerKmPerDeg+1e-9) + 1
lon := math.Ceil(plannerLonSpanDeg(sideKm, maxAbsLat)+1e-9) + 1
return int(math.Min(lat, 180) * math.Min(lon, 360))
}
// plannerLonSpanDeg bounds the degrees of longitude km can span at
// |lat| ≤ maxAbsLat: the longitude between two points on that parallel km
// apart (haversine). It is at least km/(plannerKmPerDeg·cos maxAbsLat), the
// linear conversion plannerExpandBBox and the width check use, and it grows
// at least that fast, so it also covers a leg's endpoints (no further apart
// in longitude than two points on the parallel) plus linear padding.
func plannerLonSpanDeg(km, maxAbsLat float64) float64 {
c := math.Cos(math.Min(math.Abs(maxAbsLat), 90) * math.Pi / 180)
q := math.Sin(km/(2*earthRadiusKm)) / c
if !(q < 1) {
return 360
}
return 2 * math.Asin(q) * 180 / math.Pi
}
// ─── Known positions ────────────────────────────────────────────────────────
// plannerKnown is the visible nodes with GPS, rebuilt at most every
// plannerKnownTTL (and at once when the hiding rules change). The geo checks
// and cache-key fingerprints read it; it is immutable once published.
type plannerKnown struct {
builtAt time.Time
gen string
byLat []geoPoint // every visible node with GPS, any role, by latitude
infra []plannerKnownInfra // visible repeaters/rooms, by pubkey then position
}
type plannerKnownInfra struct {
key string // lower-case pubkey
lat, lon float64
qlat, qlon int64 // plannerMilli
}
// knownSet returns the current set. A set that is only too old keeps
// serving while one caller rebuilds it; a missing one, or one built under
// other hiding rules, is rebuilt before anyone uses it.
func (p *plannerService) knownSet() *plannerKnown {
gen := p.data.filterGen()
now := p.now()
fresh := func(k *plannerKnown) bool {
return k != nil && k.gen == gen && now.Sub(k.builtAt) < plannerKnownTTL
}
k := p.known.Load()
if fresh(k) {
return k
}
if k != nil && k.gen == gen {
if !p.knownMu.TryLock() {
return k
}
} else {
p.knownMu.Lock()
}
defer p.knownMu.Unlock()
if k := p.known.Load(); fresh(k) {
return k
}
k = buildPlannerKnown(p.data.nodes(), p.data.filter(), gen, now)
p.known.Store(k)
return k
}
func buildPlannerKnown(nodes []nodeInfo, f plannerNodeFilter, gen string, now time.Time) *plannerKnown {
k := &plannerKnown{builtAt: now, gen: gen}
for i := range nodes {
n := &nodes[i]
if !n.HasGPS || !plannerFiniteCoord(n.Lat, n.Lon) || (n.Lat == 0 && n.Lon == 0) {
continue
}
if f.Visible != nil && !f.Visible(n) {
continue
}
k.byLat = append(k.byLat, geoPoint{Lat: n.Lat, Lon: n.Lon})
if (n.Role == "repeater" || n.Role == "room") && n.PublicKey != "" {
k.infra = append(k.infra, plannerKnownInfra{
key: strings.ToLower(n.PublicKey), lat: n.Lat, lon: n.Lon,
qlat: plannerMilli(n.Lat), qlon: plannerMilli(n.Lon),
})
}
}
sort.Slice(k.byLat, func(i, j int) bool { return k.byLat[i].Lat < k.byLat[j].Lat })
slices.SortFunc(k.infra, func(a, b plannerKnownInfra) int {
if c := strings.Compare(a.key, b.key); c != 0 {
return c
}
if a.qlat != b.qlat {
return compareInt64(a.qlat, b.qlat)
}
return compareInt64(a.qlon, b.qlon)
})
return k
}
func compareInt64(a, b int64) int {
switch {
case a < b:
return -1
case a > b:
return 1
}
return 0
}
// near reports whether pt is within plannerGeoRadiusKm of a visible node.
// Only the latitude band that can hold such a node is scanned.
func (k *plannerKnown) near(pt geoPoint) bool {
band := plannerGeoRadiusKm/plannerKmPerDeg + 1e-9
i := sort.Search(len(k.byLat), func(i int) bool { return k.byLat[i].Lat >= pt.Lat-band })
for ; i < len(k.byLat) && k.byLat[i].Lat <= pt.Lat+band; i++ {
if geoDistKm(pt, k.byLat[i]) <= plannerGeoRadiusKm {
return true
}
}
return false
}
// scan reports whether a visible repeater/room lies within area + nearKm,
// and fingerprints (pubkey + quantised position, in sorted order) those
// within area + fpKm: the nodes a job on area would select.
func (k *plannerKnown) scan(area geoBBox, nearKm, fpKm float64) (bool, string) {
nb, fb := plannerExpandBBox(area, nearKm), plannerExpandBBox(area, fpKm)
h := sha256.New()
var buf []byte
found := false
for i := range k.infra {
n := &k.infra[i]
if !found && plannerBBoxContains(nb, n.lat, n.lon) {
found = true
}
if plannerBBoxContains(fb, n.lat, n.lon) {
buf = append(buf[:0], n.key...)
buf = append(buf, '@')
buf = strconv.AppendInt(buf, n.qlat, 10)
buf = append(buf, ',')
buf = strconv.AppendInt(buf, n.qlon, 10)
buf = append(buf, ';')
h.Write(buf)
}
}
return found, hex.EncodeToString(h.Sum(nil)[:8])
}
// ─── Job runner ─────────────────────────────────────────────────────────────
const (
plannerStateQueued int32 = iota
plannerStateTerrain
plannerStateComputing
)
var plannerStateNames = [...]string{"queued", "loading_terrain", "computing"}
// plannerJobSpec is one endpoint's job: its key, the terrain it needs and
// the compute to run over that terrain.
type plannerJobSpec struct {
endpoint string
key string
view geoBBox
compute func(ctx context.Context, v terrainView, progress func(float64)) (any, error)
}
type plannerJob struct {
key string
endpoint string
heavy bool // coverage, viewshed: their own slot and queue limit
client string // clientLogID, for the log line only; never the IP
ctx context.Context
cancel context.CancelCauseFunc
done chan struct{}
state atomic.Int32
progress atomic.Uint64 // math.Float64bits
polledAt atomic.Int64 // p.since(now) of the last request for key
queued bool // waiting for a slot; guarded by p.mu
// Set before done is closed; read only after.
body []byte
err error
}
// since is now as a duration from p.epoch. With the real clock both carry a
// monotonic reading, so a wall-clock jump cannot abandon every job at once.
func (p *plannerService) since(now time.Time) int64 { return int64(now.Sub(p.epoch)) }
func (j *plannerJob) setProgress(f float64) {
if math.IsNaN(f) {
return
}
if f < 0 {
f = 0
} else if f > 1 {
f = 1
}
j.progress.Store(math.Float64bits(f))
}
func (j *plannerJob) status() PlannerJobStatus {
st := j.state.Load()
retry := 2
if st == plannerStateComputing {
retry = 1
}
return PlannerJobStatus{
State: plannerStateNames[st],
Progress: math.Round(math.Float64frombits(j.progress.Load())*100) / 100,
RetryAfterS: retry,
}
}
// plannerReject is a request answered without a result: 4xx/5xx + message
// and, when set, Retry-After.
type plannerReject struct {
code int
msg string
retryAfter int
}
func (rj *plannerReject) write(w http.ResponseWriter) {
w.Header().Set("Cache-Control", "no-store")
if rj.retryAfter > 0 {
w.Header().Set("Retry-After", strconv.Itoa(rj.retryAfter))
}
writeError(w, rj.code, rj.msg)
}
func plannerBadRequest(w http.ResponseWriter, msg string) {
(&plannerReject{code: http.StatusBadRequest, msg: msg}).write(w)
}
func (p *plannerService) cacheFor(heavy bool) *plannerLRU {
if heavy {
return p.covCache
}
return p.cheapCache
}
// serve answers a validated request: the cached result, or the status of
// the key's job (starting one if needed). It waits at most p.fastWait, and
// only when the terrain is already resident.
func (p *plannerService) serve(w http.ResponseWriter, r *http.Request, spec plannerJobSpec) {
heavy := spec.endpoint == plannerCoverage || spec.endpoint == plannerViewshed
now := p.now()
if body, ok := p.cacheFor(heavy).get(spec.key, now); ok {
writePlannerResult(w, body)
return
}
j, body, rej := p.attach(r, spec, heavy, now)
switch {
case rej != nil:
rej.write(w)
return
case body != nil:
writePlannerResult(w, body)
return
}
if p.fastWait > 0 && p.src.Resident(spec.view) {
t := time.NewTimer(p.fastWait)
select {
case <-j.done:
case <-t.C:
case <-r.Context().Done():
}
t.Stop()
}
select {
case <-j.done:
if j.err != nil {
p.failure(j.err).write(w)
return
}
writePlannerResult(w, j.body)
default:
writePlannerStatus(w, j.status())
}
}
// attach returns the live job for spec.key, or the result that landed since
// the caller's cache miss, or starts a job. Starting one checks capacity
// first (free), then charges the client a job, the global budget a job, and
// the client the downloads its view starts (p.src.Begin, all or nothing, in
// the step that starts them, so a tile two jobs or route LOS ask for at once
// is charged once). A refusal gives back what was charged before it, all
// under p.mu: a client over its own limit never spends everyone else's.
func (p *plannerService) attach(r *http.Request, spec plannerJobSpec, heavy bool, now time.Time) (*plannerJob, []byte, *plannerReject) {
p.mu.Lock()
defer p.mu.Unlock()
if j := p.jobs[spec.key]; j != nil {
j.polledAt.Store(p.since(now))
return j, nil, nil
}
if body, ok := p.cacheFor(heavy).get(spec.key, now); ok {
return nil, body, nil
}
if rec, ok := p.recent[spec.key]; ok {
if now.Before(rec.until) {
return nil, nil, &plannerReject{http.StatusServiceUnavailable, rec.msg, retryAfterSecs(rec.until.Sub(now))}
}
delete(p.recent, spec.key)
}
if p.closed {
return nil, nil, &plannerReject{http.StatusServiceUnavailable, "planner unavailable", plannerFullRetryS}
}
if len(p.jobs) >= plannerMaxLiveJobs || (heavy && p.covQueued >= plannerMaxQueuedCoverage) {
return nil, nil, &plannerReject{http.StatusServiceUnavailable, "planner busy", plannerFullRetryS}
}
client, _ := p.limit.clientKey(r)
if ok, wait := p.limit.take(r); !ok {
return nil, nil, &plannerReject{http.StatusTooManyRequests, "rate limited", retryAfterSecs(wait)}
}
if ok, wait := p.global.take("all"); !ok {
p.limit.refundN(r, 1)
return nil, nil, &plannerReject{http.StatusServiceUnavailable, "planner busy", retryAfterSecs(wait)}
}
// Last, so nothing can refuse the job once its downloads have started.
var retry time.Duration
if !p.src.Begin(spec.view, func(starts int) bool {
var ok bool
ok, retry = p.downloads.takeN(r, starts)
return ok
}) {
p.limit.refundN(r, 1)
p.global.refundN("all", 1)
return nil, nil, &plannerReject{http.StatusTooManyRequests, "rate limited", retryAfterSecs(retry)}
}
ctx, cancel := context.WithCancelCause(p.ctx)
j := &plannerJob{
key: spec.key, endpoint: spec.endpoint, heavy: heavy, client: clientLogID(client),
ctx: ctx, cancel: cancel, done: make(chan struct{}), queued: true,
}
j.polledAt.Store(p.since(now))
p.jobs[spec.key] = j
if heavy {
p.covQueued++
}
p.wg.Add(1)
go p.run(j, spec)
return j, nil, nil
}
func (p *plannerService) run(j *plannerJob, spec plannerJobSpec) {
defer p.wg.Done()
start := time.Now()
stop := make(chan struct{})
p.wg.Add(1)
go p.watch(j, stop)
body, err := p.execute(j, spec)
close(stop)
p.finish(j, body, err)
log.Printf("[planner] %s client=%s key=%s took=%s outcome=%s", j.endpoint, j.client,
plannerKeyHash(j.key), time.Since(start).Round(time.Millisecond), plannerOutcome(err))
}
// execute runs one job: load terrain, wait for a slot, compute, encode.
// Terrain comes first, outside the slot, so a slow download only delays its
// own job. A panic anywhere in it fails the job, not the server; the slot is
// released on every path.
func (p *plannerService) execute(j *plannerJob, spec plannerJobSpec) (body []byte, err error) {
defer func() {
if rec := recover(); rec != nil {
log.Printf("[planner] %s job %s panicked: %v\n%s", j.endpoint, plannerKeyHash(j.key), rec, debug.Stack())
body, err = nil, errPlannerPanic
}
}()
if !p.src.Resident(spec.view) {
j.state.Store(plannerStateTerrain)
}
tctx, cancel := context.WithTimeout(j.ctx, p.terrainTimeout)
v, err := p.src.View(tctx, spec.view)
cancel()
if err != nil {
return nil, j.failure(err)
}
j.state.Store(plannerStateQueued)
slots := p.cheapSlots
if j.heavy {
slots = p.covSlots
}
select {
case slots <- struct{}{}:
case <-j.ctx.Done():
return nil, context.Cause(j.ctx)
}
defer func() { <-slots }()
p.mu.Lock()
p.dequeueLocked(j)
p.mu.Unlock()
j.state.Store(plannerStateComputing)
cctx, cancel := context.WithTimeout(j.ctx, p.computeTimeout)
defer cancel()
res, err := spec.compute(cctx, v, j.setProgress)
if err == nil && cctx.Err() != nil {
// A search that ignored its deadline does not get to finish late.
err = cctx.Err()
}
if err != nil {
return nil, j.failure(err)
}
return plannerEncode(res)
}
// failure reports why the job's own context ended, when it did, rather than
// the bare context.Canceled the compute saw.
func (j *plannerJob) failure(err error) error {
if j.ctx.Err() != nil {
return context.Cause(j.ctx)
}
return err
}
// watch cancels j once no request has asked for its key for abandonAfter.
func (p *plannerService) watch(j *plannerJob, stop <-chan struct{}) {
defer p.wg.Done()
t := time.NewTicker(p.watchEvery)
defer t.Stop()
for {
select {
case <-stop:
return
case <-t.C:
if time.Duration(p.since(p.now())-j.polledAt.Load()) > p.abandonAfter {
j.cancel(errPlannerAbandoned)
return
}
}
}
}
func (p *plannerService) dequeueLocked(j *plannerJob) {
if !j.queued {
return
}
j.queued = false
if j.heavy {
p.covQueued--
}
}
// finish publishes the outcome: a result goes to the cache, a failure to
// p.recent (terrain busy for busyFor, anything else for failedFor) unless
// nobody wanted the job any more, so the next poll starts afresh. The job
// leaves p.jobs in the same critical section.
func (p *plannerService) finish(j *plannerJob, body []byte, err error) {
j.body, j.err = body, err
now := p.now()
p.mu.Lock()
switch {
case err == nil:
p.cacheFor(j.heavy).put(j.key, body, now)
case errors.Is(err, errTerrainBusy):
p.rememberLocked(j.key, now, p.busyFor, plannerMsgTerrainBusy)
case !errors.Is(err, errPlannerAbandoned) && !errors.Is(err, errPlannerClosed):
p.rememberLocked(j.key, now, p.failedFor, plannerMsgFailedRecent)
}
if p.jobs[j.key] == j {
delete(p.jobs, j.key)
}
p.dequeueLocked(j)
p.mu.Unlock()
j.cancel(nil)
close(j.done)
}
// rememberLocked answers key with msg for d, sweeping lapsed entries first
// (the map holds at most the jobs started in the last failedFor). The caller
// holds p.mu.
func (p *plannerService) rememberLocked(key string, now time.Time, d time.Duration, msg string) {
for k, rec := range p.recent {
if !now.Before(rec.until) {
delete(p.recent, k)
}
}
p.recent[key] = plannerRecent{until: now.Add(d), msg: msg}
}
// failure maps a failed job to the answer its waiting request gets; its
// Retry-After matches how long finish remembers the failure.
func (p *plannerService) failure(err error) *plannerReject {
unavailable := http.StatusServiceUnavailable
busyS, failedS := retryAfterSecs(p.busyFor), retryAfterSecs(p.failedFor)
switch {
case errors.Is(err, errTerrainBusy):
return &plannerReject{unavailable, plannerMsgTerrainBusy, busyS}
case errors.Is(err, errPlannerAbandoned), errors.Is(err, errPlannerClosed):
return &plannerReject{unavailable, "planner job cancelled", 1}
case errors.Is(err, errTerrainUnavailable):
return &plannerReject{unavailable, "terrain unavailable", failedS}
case errors.Is(err, errTerrainTooManyTiles):
return &plannerReject{code: http.StatusBadRequest, msg: plannerErrTooManyTiles}
case errors.Is(err, context.DeadlineExceeded):
return &plannerReject{unavailable, "planner timed out", failedS}
}
return &plannerReject{http.StatusInternalServerError, "planner failed", failedS}
}
// plannerOutcome is the log line's outcome.
func plannerOutcome(err error) string {
switch {
case err == nil:
return "ok"
case errors.Is(err, errTerrainBusy):
return "terrain_busy"
case errors.Is(err, errTerrainUnavailable):
return "terrain_unavailable"
case errors.Is(err, errTerrainTooManyTiles):
return "too_many_tiles"
case errors.Is(err, context.DeadlineExceeded):
return "timeout"
case errors.Is(err, errPlannerAbandoned):
return "abandoned"
case errors.Is(err, errPlannerClosed):
return "closed"
case errors.Is(err, context.Canceled):
return "cancelled"
case errors.Is(err, errPlannerPanic):
return "panic"
}
return "error: " + err.Error()
}
// plannerKeyHash names a key in logs without revealing the coordinates in it.
func plannerKeyHash(key string) string {
sum := sha256.Sum256([]byte(key))
return hex.EncodeToString(sum[:6])
}
func plannerEncode(v any) ([]byte, error) {
b, err := json.Marshal(v)
if err != nil {
return nil, err
}
return append(b, '\n'), nil // byte-identical to json.Encoder output
}
func writePlannerResult(w http.ResponseWriter, body []byte) {
w.Header().Set("Cache-Control", plannerCacheControl)
writeJSONBytes(w, body)
}
func writePlannerStatus(w http.ResponseWriter, st PlannerJobStatus) {
w.Header().Set("Cache-Control", "no-store")
w.Header().Set("Retry-After", strconv.Itoa(st.RetryAfterS))
writeJSONStatus(w, http.StatusAccepted, st)
}
// ─── Result cache ───────────────────────────────────────────────────────────
// plannerLRU holds encoded results, bounded by entry count and total bytes;
// entries expire ttl after they were stored. Bodies are never modified after
// put, so get hands out the stored slice.
type plannerLRU struct {
mu sync.Mutex
ttl time.Duration
maxEntry int // bytes; put skips a bigger entry
cache *lru[string, plannerLRUEntry]
}
type plannerLRUEntry struct {
body []byte
exp time.Time
}
func newPlannerLRU(maxItems, maxBytes int, ttl time.Duration) *plannerLRU {
return &plannerLRU{ttl: ttl, maxEntry: maxBytes / 4,
cache: newLRU(maxItems, maxBytes, plannerEntrySize)}
}
func plannerEntrySize(key string, e plannerLRUEntry) int { return len(key) + len(e.body) }
func (c *plannerLRU) get(key string, now time.Time) ([]byte, bool) {
c.mu.Lock()
defer c.mu.Unlock()
e, ok := c.cache.Get(key)
if !ok {
return nil, false
}
if !now.Before(e.exp) {
c.cache.Remove(key)
return nil, false
}
return e.body, true
}
// put stores body; one entry over a quarter of the byte budget is not
// cached, so it cannot flush everything else.
func (c *plannerLRU) put(key string, body []byte, now time.Time) {
e := plannerLRUEntry{body: body, exp: now.Add(c.ttl)}
if plannerEntrySize(key, e) > c.maxEntry {
return
}
c.mu.Lock()
defer c.mu.Unlock()
c.cache.Put(key, e)
}
func (c *plannerLRU) len() int {
c.mu.Lock()
defer c.mu.Unlock()
return c.cache.Len()
}