Basemap Pusher: catalog and distribution gateway for existing tiles

A Go service that scans existing basemap tile directories and vector files,
catalogues them in SQLite, issues scoped access tokens, and serves tiles and
downloads to downstream systems. It deliberately does not generate or process
raster data: GIS software produces the tiles, this service catalogues,
authorises and distributes them.

Capabilities
- scans basemap tile directories (manifest-based or raw z/x/y) and vector
  assets (.geojson, .json, .zip, shapefiles with sidecars)
- token auth with per-resource grants, expiry and coarse scopes (read, slice)
- resource health inspection flags a moved or deleted tile root before a client
  hits a 404
- downstream push with exponential-backoff retries and manual re-queue
- image slicing jobs driven by the GDAL bundled with QGIS, including VRT
  mosaicking so successive drone flights accumulate into one seamless layer
- a narrow, non-admin slicing API for external callers: submit, poll,
  idempotent by job code, completion callback
- ops console covering health, ledger, tokens, pushes, scans, slicing and
  service info
- native Windows service install/start/stop with crash recovery, auto-start and
  a rotating log file, so no NSSM or WinSW wrapper is needed

Verified with 49 tests plus live runs against real tile data and real GDAL.
This commit is contained in:
2026-10-16 10:36:12 +08:00
commit 747eed63b0
55 changed files with 13526 additions and 0 deletions
+242
View File
@@ -0,0 +1,242 @@
package main
import (
"context"
"errors"
"fmt"
"log"
"net/http"
"os"
"os/signal"
"path/filepath"
"strconv"
"strings"
"syscall"
"time"
"tile-server/api-go/internal/basemap"
"tile-server/api-go/internal/basemapapi"
"tile-server/api-go/internal/config"
)
const shutdownGrace = 15 * time.Second
type cliArgs struct {
command string
envFile string
}
func main() {
args, err := parseArgs(os.Args[1:])
if err != nil {
log.Fatalf("parse arguments: %v", err)
}
if args.envFile != "" {
if err := os.Setenv("APP_ENV_FILE", args.envFile); err != nil {
log.Fatalf("set APP_ENV_FILE: %v", err)
}
}
// Service management verbs (install / uninstall / start / stop / status).
if handled, err := handleServiceArgs(args.command, args.envFile); handled {
if err != nil {
log.Fatalf("%v", err)
}
return
}
// When the SCM launched us there is no console and no SIGINT, so the service
// handler owns the lifecycle instead of the signal handler.
if runAsWindowsService() {
return
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if err := run(ctx); err != nil {
log.Fatalf("%v", err)
}
}
func parseArgs(argv []string) (cliArgs, error) {
var args cliArgs
for i := 0; i < len(argv); i++ {
switch argv[i] {
case "--env-file":
if i+1 >= len(argv) {
return args, errors.New("--env-file requires a path")
}
args.envFile = argv[i+1]
i++
default:
if args.command == "" {
args.command = argv[i]
}
}
}
return args, nil
}
// run boots the service and blocks until ctx is cancelled or the listener dies.
// It owns every resource it creates.
func run(ctx context.Context) error {
cfg, err := config.Load()
if err != nil {
return fmt.Errorf("load config: %w", err)
}
// The admin surface can create tokens that read every basemap, so it must
// never be reachable off-host without credentials.
if cfg.BindsToNonLoopback() && !cfg.HasAdminCredentials() {
return fmt.Errorf("refusing to listen on %s without admin credentials: set ADMIN_TOKEN or ADMIN_USER/ADMIN_PASSWORD", cfg.ListenAddr())
}
store, err := basemap.OpenStore(basemap.StoreConfig{
SQLitePath: cfg.SQLitePath,
ScanRoot: cfg.BasemapScanRoot,
VectorScanRoot: cfg.VectorScanRoot,
APIBaseURL: cfg.APIBaseURL,
TileBaseURL: cfg.TilePublicBaseURL,
VectorBaseURL: cfg.VectorPublicBaseURL,
AutoScanOnStart: cfg.AutoScanOnStart,
TokenDefaultTTL: cfg.TokenDefaultTTL,
TileJobCommand: cfg.TileJobCommand,
TileJobVRTCommand: cfg.TileJobVRTCommand,
TileJobLogDir: cfg.TileJobLogDir,
HealthCheckInterval: cfg.HealthCheckInterval,
})
if err != nil {
return fmt.Errorf("open sqlite store: %w", err)
}
defer func() {
if err := store.Close(); err != nil {
log.Printf("close store: %v", err)
}
}()
systemInfo := basemap.SystemInfo{
ServiceName: cfg.ServiceName,
ServiceVersion: cfg.ServiceVersion,
Commit: cfg.Commit,
Env: cfg.Env,
APIBaseURL: cfg.APIBaseURL,
TileBaseURL: cfg.TilePublicBaseURL,
VectorBaseURL: cfg.VectorPublicBaseURL,
SQLitePath: cfg.SQLitePath,
ScanRoot: cfg.BasemapScanRoot,
VectorScanRoot: cfg.VectorScanRoot,
TileJobCommand: cfg.TileJobCommand,
StartedAt: time.Now().UTC(),
}
if cfg.AutoScanOnStart && strings.TrimSpace(cfg.BasemapScanRoot) != "" {
if _, err := store.RunScan(context.Background(), "local-basemaps"); err != nil {
log.Printf("startup scan skipped: %v", err)
} else {
log.Printf("startup scan completed for %s", cfg.BasemapScanRoot)
}
}
if cfg.AutoScanOnStart && strings.TrimSpace(cfg.VectorScanRoot) != "" {
if _, err := store.RunVectorScan(context.Background()); err != nil {
log.Printf("startup vector scan skipped: %v", err)
} else {
log.Printf("startup vector scan completed for %s", cfg.VectorScanRoot)
}
}
// Health inspection, push retries and the tile queue run in the background.
store.StartBackgroundWorkers()
server, err := basemapapi.New(store, systemInfo, basemapapi.Options{
Admin: basemapapi.AdminAuth{
Token: cfg.AdminToken,
User: cfg.AdminUser,
Password: cfg.AdminPassword,
},
CORSAllowedOrigins: cfg.CORSAllowedOrigins,
})
if err != nil {
return fmt.Errorf("init api server: %w", err)
}
httpServer := &http.Server{
Addr: cfg.ListenAddr(),
Handler: server.Handler(),
ReadHeaderTimeout: 5 * time.Second,
}
cleanupPID, err := writePIDFile(strings.TrimSpace(os.Getenv("RS_API_PID_FILE")))
if err != nil {
return fmt.Errorf("write pid file: %w", err)
}
if cleanupPID != nil {
defer cleanupPID()
}
log.Printf("api base url: %s", cfg.APIBaseURL)
log.Printf("tile public base url: %s", cfg.TilePublicBaseURL)
log.Printf("vector public base url: %s", cfg.VectorPublicBaseURL)
log.Printf("sqlite path: %s", cfg.SQLitePath)
log.Printf("scan root: %s", cfg.BasemapScanRoot)
log.Printf("vector scan root: %s", cfg.VectorScanRoot)
if cfg.HasAdminCredentials() {
log.Printf("admin auth: enabled")
} else {
log.Printf("admin auth: disabled (loopback only)")
}
serveErr := make(chan error, 1)
go func() {
log.Printf("basemap pusher listening on http://%s", cfg.ListenAddr())
if err := httpServer.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
serveErr <- err
return
}
serveErr <- nil
}()
select {
case err := <-serveErr:
if err != nil {
return fmt.Errorf("listen and serve: %w", err)
}
return nil
case <-ctx.Done():
log.Printf("shutdown signal received, draining connections")
shutdownCtx, cancel := context.WithTimeout(context.Background(), shutdownGrace)
defer cancel()
if err := httpServer.Shutdown(shutdownCtx); err != nil {
log.Printf("graceful shutdown incomplete: %v", err)
_ = httpServer.Close()
}
if err := <-serveErr; err != nil {
log.Printf("server stopped with error: %v", err)
}
log.Printf("shutdown complete")
return nil
}
}
func writePIDFile(path string) (func(), error) {
if path == "" {
return nil, nil
}
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
return nil, err
}
pidText := strconv.Itoa(os.Getpid())
if err := os.WriteFile(path, []byte(pidText+"\n"), 0o644); err != nil {
return nil, err
}
cleanup := func() {
content, err := os.ReadFile(path)
if err != nil {
return
}
if strings.TrimSpace(string(content)) == pidText {
_ = os.Remove(path)
}
}
return cleanup, nil
}
+8
View File
@@ -0,0 +1,8 @@
//go:build !windows
package main
// Service management is Windows-only; other platforms run the console binary.
func handleServiceArgs(command, envFile string) (bool, error) { return false, nil }
func runAsWindowsService() bool { return false }
+376
View File
@@ -0,0 +1,376 @@
//go:build windows
package main
import (
"context"
"fmt"
"log"
"os"
"path/filepath"
"strings"
"time"
"golang.org/x/sys/windows/svc"
"golang.org/x/sys/windows/svc/mgr"
)
const (
serviceName = "BasemapPusher"
serviceDisplayName = "Basemap Pusher"
serviceDescription = "Internal catalog and push gateway for existing basemap tiles and vector assets."
// appEnvFileFlag is baked into the service command line so the service finds
// its config file even though the SCM starts it in C:\Windows\System32.
appEnvFileFlag = "--env-file"
)
// handleServiceArgs implements the install/uninstall/start/stop/status verbs.
// The bool reports whether the verb was recognised.
func handleServiceArgs(command, envFile string) (bool, error) {
switch command {
case "install":
return true, installService(envFile)
case "uninstall":
return true, uninstallService()
case "start":
return true, startService()
case "stop":
return true, stopService()
case "status":
return true, serviceStatus()
default:
return false, nil
}
}
// runAsWindowsService reports whether the process was launched by the SCM, and
// if so runs it to completion. It returns false for a normal console launch.
func runAsWindowsService() bool {
isService, err := svc.IsWindowsService()
if err != nil || !isService {
return false
}
restoreLog := setupServiceLogging()
defer restoreLog()
if err := svc.Run(serviceName, &serviceHandler{}); err != nil {
log.Printf("windows service run: %v", err)
}
return true
}
type serviceHandler struct{}
func (h *serviceHandler) Execute(args []string, r <-chan svc.ChangeRequest, changes chan<- svc.Status) (bool, uint32) {
changes <- svc.Status{State: svc.StartPending}
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
done := make(chan error, 1)
go func() { done <- run(ctx) }()
changes <- svc.Status{State: svc.Running, Accepts: svc.AcceptStop | svc.AcceptShutdown}
for {
select {
case err := <-done:
if err != nil {
log.Printf("service stopped with error: %v", err)
changes <- svc.Status{State: svc.Stopped}
return false, 1
}
changes <- svc.Status{State: svc.Stopped}
return false, 0
case change := <-r:
switch change.Cmd {
case svc.Interrogate:
changes <- change.CurrentStatus
case svc.Stop, svc.Shutdown:
changes <- svc.Status{State: svc.StopPending}
cancel()
// Give the HTTP server its drain window before reporting stopped.
select {
case <-done:
case <-time.After(shutdownGrace + 5*time.Second):
log.Printf("service did not stop within the drain window")
}
changes <- svc.Status{State: svc.Stopped}
return false, 0
}
}
}
}
func installService(envFile string) error {
exe, err := os.Executable()
if err != nil {
return fmt.Errorf("resolve executable: %w", err)
}
exe, err = filepath.Abs(exe)
if err != nil {
return fmt.Errorf("resolve executable path: %w", err)
}
resolvedEnv := envFile
if resolvedEnv == "" {
resolvedEnv = findDefaultEnvFile(filepath.Dir(exe))
}
if resolvedEnv == "" {
return fmt.Errorf("no config/service.env found next to %s; pass --env-file <path> to install", exe)
}
resolvedEnv, err = filepath.Abs(resolvedEnv)
if err != nil {
return fmt.Errorf("resolve env file: %w", err)
}
if _, err := os.Stat(resolvedEnv); err != nil {
return fmt.Errorf("env file %s is not readable: %w", resolvedEnv, err)
}
manager, err := mgr.Connect()
if err != nil {
return fmt.Errorf("connect to the service manager (run this as Administrator): %w", err)
}
defer manager.Disconnect()
if existing, err := manager.OpenService(serviceName); err == nil {
existing.Close()
return fmt.Errorf("service %q already exists; run uninstall first", serviceName)
}
service, err := manager.CreateService(serviceName, exe, mgr.Config{
DisplayName: serviceDisplayName,
Description: serviceDescription,
StartType: mgr.StartAutomatic,
}, appEnvFileFlag, resolvedEnv)
if err != nil {
return fmt.Errorf("create service: %w", err)
}
defer service.Close()
// Restart on failure: 5s, 15s, 60s, then keep trying within the reset window.
if err := service.SetRecoveryActions([]mgr.RecoveryAction{
{Type: mgr.ServiceRestart, Delay: 5 * time.Second},
{Type: mgr.ServiceRestart, Delay: 15 * time.Second},
{Type: mgr.ServiceRestart, Delay: 60 * time.Second},
}, 86400); err != nil {
log.Printf("warning: could not set recovery actions: %v", err)
}
log.Printf("installed service %q", serviceName)
log.Printf(" executable: %s", exe)
log.Printf(" env file: %s", resolvedEnv)
log.Printf(" start with: %s start", exe)
return nil
}
func uninstallService() error {
manager, err := mgr.Connect()
if err != nil {
return fmt.Errorf("connect to the service manager (run this as Administrator): %w", err)
}
defer manager.Disconnect()
service, err := manager.OpenService(serviceName)
if err != nil {
return fmt.Errorf("service %q is not installed", serviceName)
}
defer service.Close()
if status, err := service.Query(); err == nil && status.State != svc.Stopped {
_, _ = service.Control(svc.Stop)
time.Sleep(2 * time.Second)
}
if err := service.Delete(); err != nil {
return fmt.Errorf("delete service: %w", err)
}
log.Printf("uninstalled service %q", serviceName)
return nil
}
func startService() error {
manager, err := mgr.Connect()
if err != nil {
return fmt.Errorf("connect to the service manager: %w", err)
}
defer manager.Disconnect()
service, err := manager.OpenService(serviceName)
if err != nil {
return fmt.Errorf("service %q is not installed", serviceName)
}
defer service.Close()
if err := service.Start(); err != nil {
return fmt.Errorf("start service: %w", err)
}
log.Printf("started service %q", serviceName)
return nil
}
func stopService() error {
manager, err := mgr.Connect()
if err != nil {
return fmt.Errorf("connect to the service manager: %w", err)
}
defer manager.Disconnect()
service, err := manager.OpenService(serviceName)
if err != nil {
return fmt.Errorf("service %q is not installed", serviceName)
}
defer service.Close()
status, err := service.Control(svc.Stop)
if err != nil {
return fmt.Errorf("stop service: %w", err)
}
deadline := time.Now().Add(30 * time.Second)
for status.State != svc.Stopped && time.Now().Before(deadline) {
time.Sleep(time.Second)
status, err = service.Query()
if err != nil {
return fmt.Errorf("query service: %w", err)
}
}
log.Printf("stopped service %q", serviceName)
return nil
}
func serviceStatus() error {
manager, err := mgr.Connect()
if err != nil {
return fmt.Errorf("connect to the service manager: %w", err)
}
defer manager.Disconnect()
service, err := manager.OpenService(serviceName)
if err != nil {
return fmt.Errorf("service %q is not installed", serviceName)
}
defer service.Close()
status, err := service.Query()
if err != nil {
return fmt.Errorf("query service: %w", err)
}
names := map[svc.State]string{
svc.Stopped: "stopped",
svc.StartPending: "start pending",
svc.StopPending: "stop pending",
svc.Running: "running",
svc.ContinuePending: "continue pending",
svc.PausePending: "pause pending",
svc.Paused: "paused",
}
name, ok := names[status.State]
if !ok {
name = fmt.Sprintf("state %d", status.State)
}
fmt.Printf("%s: %s\n", serviceName, name)
return nil
}
// findDefaultEnvFile looks in the usual layouts: next to the executable, then
// one and two levels up (services/api-go -> repo root).
func findDefaultEnvFile(startDir string) string {
candidates := []string{
filepath.Join(startDir, "config", "service.env"),
filepath.Join(startDir, "..", "config", "service.env"),
filepath.Join(startDir, "..", "..", "config", "service.env"),
}
for _, candidate := range candidates {
if _, err := os.Stat(candidate); err == nil {
return candidate
}
}
return ""
}
// setupServiceLogging points the standard logger at a file, because a Windows
// service has no console and would otherwise discard every log line. It returns
// a restore func that is safe to call even when nothing was configured.
func setupServiceLogging() func() {
path := strings.TrimSpace(os.Getenv("SERVICE_LOG_FILE"))
if path == "" {
exe, err := os.Executable()
if err != nil {
return func() {}
}
path = filepath.Join(filepath.Dir(exe), "logs", "basemap-pusher.log")
}
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
return func() {}
}
writer, err := newRotatingFileWriter(path, serviceLogMaxBytes)
if err != nil {
return func() {}
}
log.SetOutput(writer)
log.Printf("service log: %s (rotates at %d MB)", path, serviceLogMaxBytes>>20)
return func() { _ = writer.Close() }
}
const serviceLogMaxBytes = 10 << 20
// rotatingFileWriter appends to one file and rolls it to ".1" once it grows
// past maxBytes, so a long-running service cannot fill the disk.
type rotatingFileWriter struct {
path string
maxBytes int64
file *os.File
size int64
}
func newRotatingFileWriter(path string, maxBytes int64) (*rotatingFileWriter, error) {
writer := &rotatingFileWriter{path: path, maxBytes: maxBytes}
if err := writer.open(); err != nil {
return nil, err
}
return writer, nil
}
func (w *rotatingFileWriter) open() error {
file, err := os.OpenFile(w.path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
if err != nil {
return err
}
info, err := file.Stat()
if err != nil {
file.Close()
return err
}
w.file = file
w.size = info.Size()
return nil
}
func (w *rotatingFileWriter) Write(p []byte) (int, error) {
if w.maxBytes > 0 && w.size+int64(len(p)) > w.maxBytes {
w.roll()
}
n, err := w.file.Write(p)
w.size += int64(n)
return n, err
}
func (w *rotatingFileWriter) roll() {
if w.file != nil {
_ = w.file.Close()
}
// Windows refuses to rename onto an existing path, so drop the old roll.
_ = os.Remove(w.path + ".1")
_ = os.Rename(w.path, w.path+".1")
w.size = 0
if err := w.open(); err != nil {
// Fall back to appending to the original path if the reopen failed.
_ = err
}
}
func (w *rotatingFileWriter) Close() error {
if w.file == nil {
return nil
}
return w.file.Close()
}
@@ -0,0 +1,47 @@
//go:build windows
package main
import (
"os"
"path/filepath"
"strings"
"testing"
)
func TestRotatingFileWriterRollsOver(t *testing.T) {
dir := t.TempDir()
path := filepath.Join(dir, "svc.log")
writer, err := newRotatingFileWriter(path, 64)
if err != nil {
t.Fatalf("open writer: %v", err)
}
defer writer.Close()
for i := 0; i < 10; i++ {
if _, err := writer.Write([]byte(strings.Repeat("x", 20) + "\n")); err != nil {
t.Fatalf("write %d: %v", i, err)
}
}
if _, err := os.Stat(path); err != nil {
t.Fatalf("current log missing: %v", err)
}
if _, err := os.Stat(path + ".1"); err != nil {
t.Fatalf("expected a rolled file at %s.1: %v", path, err)
}
}
func TestSetupServiceLoggingUsesConfiguredPath(t *testing.T) {
dir := t.TempDir()
path := filepath.Join(dir, "nested", "service.log")
t.Setenv("SERVICE_LOG_FILE", path)
restore := setupServiceLogging()
defer restore()
if _, err := os.Stat(path); err != nil {
t.Fatalf("expected the log file at %s: %v", path, err)
}
}