Documentation
¶
Overview ¶
Package chargers serves the chargers.pmtiles archive from the rivolt API: the entire ~10 MB file is fetched once at startup (or first request), parsed in-memory, and queries against it run fully server-side. This replaces the SPA's per-tile fan-out over the same archive — for long corridors that was ~hundreds of HTTPS range requests per planner re-render, saturating the browser's per-origin socket pool and feeling sluggish even after the upstream tile server moved to tmpfs.
Wire path: tiles nginx pod serves /chargers.pmtiles → rivolt fetches it once via the in-cluster Service → keeps a *[]byte in memory → answers /api/maps/chargers-along with a flat JSON list.
Index ¶
- Constants
- Variables
- func PointQueryPath(lat, lon, radiusKm float64) [][2]float64
- func ThinPath(path [][2]float64, max int) [][2]float64
- type Archive
- func (a *Archive) BuiltAt() time.Time
- func (a *Archive) LoadedAt() time.Time
- func (a *Archive) Nearest(lat, lon, maxM float64, filter Filter) (POI, bool, error)
- func (a *Archive) QueryCorridor(path [][2]float64, filter Filter, opts QueryCorridorOptions) ([]POI, error)
- func (a *Archive) QueryLayers(path [][2]float64, kinds []string, opts LayerOptions) (LayerResult, error)
- func (a *Archive) Refresh(ctx context.Context) (changed bool, err error)
- func (a *Archive) Reload(ctx context.Context) error
- func (a *Archive) Within(lat, lon, maxM float64, filter Filter) ([]NearPOI, error)
- type CorridorPOI
- type Filter
- type LayerOptions
- type LayerResult
- type NearPOI
- type POI
- type QueryCorridorOptions
Constants ¶
const ( // MaxPathPoints is the most route points a scan walks; a longer polyline (up to MaxRoutePoints) is thinned to it. MaxPathPoints = 5000 // MaxCorridorKm is the widest search band accepted (half-width). MaxCorridorKm = 50.0 )
Limits on a corridor query, so one request cannot ask for a continent of tiles.
const ( // DefaultLayerLimit and MaxLayerLimit bound one page of a layer query. DefaultLayerLimit = 300 MaxLayerLimit = 1000 )
const MaxRoutePoints = 200_000
MaxRoutePoints is the longest route polyline an API caller may send. A long drive's polyline has tens of thousands of points (a 1,300 km route is about 25,000), far over MaxPathPoints; the handler thins it first.
Variables ¶
var ( // ErrBadPath is a path with a coordinate that is not a number. ErrBadPath = errors.New("chargers: path has a coordinate that is not a number") // ErrQueryTooLarge is a path with too many points or spanning too many tiles. ErrQueryTooLarge = errors.New("chargers: query is too large") )
var CorridorPresets = map[string]map[string]float64{ "close": {"dcfc": 3.2, "l2": 1.6, "hotels": 8, "camp": 8}, "normal": LayerKindKm, "wide": {"dcfc": 16, "l2": 8, "hotels": 32, "camp": 32}, }
CorridorPresets are the planner settings' "how far from the route" choices, as per-kind half-widths in km (the miles in the setting's labels: close 2/1/5, normal 5/3/10, wide 10/5/20 for fast / Level 2 / hotels and campgrounds). Normal is LayerKindKm, so no preset set means no change.
var ErrBadKinds = errors.New("chargers: kinds must be one or more of dcfc, l2, hotels, camp")
ErrBadKinds is an empty, unknown or repeated-beyond-reason list of layer kinds.
var LayerKindKm = map[string]float64{"dcfc": 8, "l2": 4.8, "hotels": 16, "camp": 16}
LayerKindKm is the default half-width of the corridor for each layer kind, used when the request names no corridor_km: a fast charger a driver would detour for is within 5 miles of the route, a Level 2 within 3 (nobody drives further for slow charging), a hotel or a campground within 10. The query runs once at the widest requested width and each station is then kept only within its own kind's width.
Functions ¶
func PointQueryPath ¶ added in v0.40.0
PointQueryPath is the path to give QueryCorridor to ask for everything within radiusKm of a point (use CorridorKm = radiusKm, and filter the answer by distance if the exact circle matters). QueryCorridor is a band along a path and drops a station whose nearest point on the path is an end of it, so a tiny path around a point, or the point twice, finds nothing at all: only a station in a thin strip beside it would pass. A north-south segment through the point, longer than the radius on each side, keeps every station within the radius inside the band.
func ThinPath ¶ added in v0.39.2
ThinPath returns path with points dropped so that at most max remain, keeping the first and the last and spacing the rest evenly along the route, so the shape follows the road to within about the spacing (a few hundred metres on a continental route, against a corridor of kilometres). A path that is already short enough, or has a coordinate that is not a number (QueryCorridor refuses that), is returned as it is.
Types ¶
type Archive ¶
type Archive struct {
// contains filtered or unexported fields
}
Archive holds the entire chargers PMTiles file in memory plus a decoded root directory. Leaf directories are decoded lazily and cached in leafDirs. Safe for concurrent readers; the only writer is Reload.
func New ¶
New returns an empty archive; the caller drives Reload to populate it (so startup wiring can defer the fetch until the URL is known).
func (*Archive) BuiltAt ¶ added in v0.40.24
LoadedAt returns the timestamp of the last successful Reload, or the zero Time if the archive has not yet been loaded. BuiltAt is when the archive file was last modified at its source (the Last-Modified the server sent with it): the nearest thing the file has to a build date. Zero when the server sent none, or nothing is loaded.
func (*Archive) Nearest ¶ added in v0.32.0
Nearest returns the closest charger passing filter within maxM meters of (lat, lon). Used to attribute a recorded charging session to the station (and network) it happened at. Searches the point's tile and its eight neighbours, so maxM must stay well under a z14 tile (~2.4 km at the equator). Concurrent-safe.
func (*Archive) QueryCorridor ¶
func (a *Archive) QueryCorridor(path [][2]float64, filter Filter, opts QueryCorridorOptions) ([]POI, error)
QueryCorridor returns all chargers passing `filter` within `corridorKm` of any non-endpoint point on `path`. Concurrent-safe. The query is validated first (see planCorridor); ErrBadPath and ErrQueryTooLarge say why it was refused, and a done opts.Context stops it early with the context's error.
func (*Archive) QueryLayers ¶ added in v0.40.23
func (a *Archive) QueryLayers(path [][2]float64, kinds []string, opts LayerOptions) (LayerResult, error)
QueryLayers returns the stations of the requested kinds along the route in route order (nearest the start first), with their distance along and off the route. One scan serves every kind. Archive only: no call leaves the server.
func (*Archive) Refresh ¶ added in v0.38.8
Refresh reloads the archive only when the file behind the URL changed (a conditional GET on the ETag of the loaded copy), so a rebuilt archive is picked up without a restart. changed is false when the server says 304; a server that sends no ETag gets the full file each time (and reports changed). A failed fetch leaves the loaded archive in place.
func (*Archive) Reload ¶
Reload fetches the .pmtiles file from a.url, parses the header and root directory, and atomically swaps the live state. Existing in-flight queries continue to read the previous bytes via their captured RLock; the next query sees the new state.
func (*Archive) Within ¶ added in v0.33.0
Within returns every charger passing filter within maxM meters of (lat, lon), nearest first: the whole site, so a caller can tell a co-located one (a Supercharger beside RAN) from a single network. Same tile search and maxM limit as Nearest. Concurrent-safe.
type CorridorPOI ¶ added in v0.40.23
type CorridorPOI struct {
POI
AlongKm float64 `json:"alongKm"`
OffKm float64 `json:"offKm"`
Kinds []string `json:"kinds"`
}
CorridorPOI is a station with where it sits against the route: AlongKm from the route's start to the closest point on it, OffKm from the route to the station, and Kinds, the requested layers it belongs to.
type LayerOptions ¶ added in v0.40.23
type LayerOptions struct {
QueryCorridorOptions
AfterKm float64
Limit int
// Paged asks for the route-ordered pages (first Limit, then NextAfterKm as AfterKm). Without it (and with no AfterKm), a corridor with more
// stations than Limit comes back as a set spread along the whole route (spreadAlongRoute), because a client that shows one capped page
// would otherwise show only the first stretch of a long route.
Paged bool
// KindKm, when set, replaces LayerKindKm as each kind's half-width (a CorridorPresets entry); ignored when CorridorKm is set.
KindKm map[string]float64
// MinAlongKm drops the chargers (fast and Level 2, not hotels or campgrounds) closer than this to the route's start, along the route. It is
// applied before paging, so Total and the pages agree.
MinAlongKm float64
// MinFastKW drops a station from the fast layer when its power is known and below this. Unknown power stays (as MinPowerKW does).
MinFastKW float64
// Accept, when set, keeps only stations it returns true for (applied before paging, so Total and the pages agree).
Accept func(POI) bool
}
LayerOptions are the corridor options plus paging along the route: only stations with AlongKm past AfterKm, at most Limit.
type LayerResult ¶ added in v0.40.23
type LayerResult struct {
POIs []CorridorPOI
Total int
NextAfterKm *float64
AsOf string
RouteKm float64
}
LayerResult is one page. Total counts every station in the corridor for the requested kinds, so a client can say "showing 300 of 1,240". NextAfterKm is set when more follow: ask again with it as AfterKm. AsOf is the newest export date among the stations found, else the archive file's own date (the build date, not live data); RouteKm is the length of the route as searched.
type POI ¶
type POI struct {
Lat float64 `json:"lat"`
Lon float64 `json:"lon"`
Name string `json:"name,omitempty"`
IsDCFC bool `json:"isDCFC"`
IsL2 bool `json:"isL2"`
MaxPowerKW float64 `json:"maxPowerKW,omitempty"`
FacilityType string `json:"facilityType,omitempty"`
EVNetwork string `json:"evNetwork,omitempty"`
EVPricing string `json:"evPricing,omitempty"`
EntityID string `json:"entityID,omitempty"`
DCFCCount int `json:"dcfcCount,omitempty"`
L2Count int `json:"l2Count,omitempty"`
SocketTesla bool `json:"socketTeslaSupercharger,omitempty"`
SocketCCS1 bool `json:"socketType1Combo,omitempty"`
SocketChademo bool `json:"socketChademo,omitempty"`
// SocketJ1772 and SocketNEMA1450 are the AC connectors the listing flags
// (the archive's socket:type1 and socket:nema_1450).
SocketJ1772 bool `json:"socketJ1772,omitempty"`
SocketNEMA1450 bool `json:"socketNema1450,omitempty"`
// The campground fields come from the Recreation.gov (RIDB) step of the
// archive build; zero on every NREL-only station. HookupAmps is the
// highest electric hookup of any campsite, ElectricSites of Sites the
// number with power. AsOf is the export's date ("2026-10-20").
HookupAmps int `json:"hookupAmps,omitempty"`
ElectricSites int `json:"electricSites,omitempty"`
Sites int `json:"sites,omitempty"`
Reservable bool `json:"reservable,omitempty"`
Source string `json:"source,omitempty"`
// RIDBID is the Recreation.gov FacilityID of the campground, set on a
// station that came from, or was merged with, a RIDB record.
RIDBID string `json:"ridbID,omitempty"`
AsOf string `json:"asof,omitempty"`
}
POI is one charging-station feature as the SPA expects it. Fields mirror the SPA's POI type in web/src/lib/poi.ts so the renderer code is unchanged. Names are camelCase on the JSON wire to match the existing TS type.
func (POI) IsCampground ¶ added in v0.38.9
IsCampground reports whether poi is a campground or RV park with a way to plug in: a listed hookup (HookupAmps), a Level 2 stall or a NEMA 14-50.
type QueryCorridorOptions ¶
type QueryCorridorOptions struct {
CorridorKm float64
EndpointTrimMeter float64
MinPowerKW float64
// If true, includes destinations that project onto the route's
// endpoint segment. Off by default (matches SPA behaviour).
IncludeEndpoints bool
// Context, when set, ends the query early once it is done (a client that
// went away, a request timeout).
Context context.Context
}
QueryCorridorOptions tunes the corridor scan; zero values pick the SPA defaults.