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
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,108 @@
package basemapapi
import (
"context"
"io"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"testing"
"tile-server/api-go/internal/basemap"
)
func TestCompatibilityRoutes(t *testing.T) {
ctx := context.Background()
root := t.TempDir()
tileRoot := filepath.Join(root, "tiles")
vectorRoot := filepath.Join(root, "vectors")
sqlitePath := filepath.Join(root, "basemap.db")
if err := os.MkdirAll(filepath.Join(tileRoot, "google_image", "0", "0"), 0o755); err != nil {
t.Fatalf("mkdir tile root: %v", err)
}
if err := os.WriteFile(filepath.Join(tileRoot, "google_image", "0", "0", "0.webp"), []byte("tile"), 0o644); err != nil {
t.Fatalf("write tile: %v", err)
}
if err := os.MkdirAll(vectorRoot, 0o755); err != nil {
t.Fatalf("mkdir vector root: %v", err)
}
if err := os.WriteFile(filepath.Join(vectorRoot, "全国行政区.geojson"), []byte(`{"type":"FeatureCollection","features":[]}`), 0o644); err != nil {
t.Fatalf("write geojson: %v", err)
}
store, err := basemap.OpenStore(basemap.StoreConfig{
SQLitePath: sqlitePath,
ScanRoot: tileRoot,
VectorScanRoot: vectorRoot,
APIBaseURL: "http://127.0.0.1:8910",
TileBaseURL: "http://127.0.0.1:8910",
VectorBaseURL: "http://127.0.0.1:8910",
})
if err != nil {
t.Fatalf("open store: %v", err)
}
defer func() {
if err := store.Close(); err != nil {
t.Fatalf("close store: %v", err)
}
}()
if _, err := store.RunScan(ctx, "local-basemaps"); err != nil {
t.Fatalf("run scan: %v", err)
}
if _, err := store.RunVectorScan(ctx); err != nil {
t.Fatalf("run vector scan: %v", err)
}
token, err := store.CreateToken(ctx, basemap.CreateTokenInput{
Name: "compat",
BasemapCodes: []string{"google_image"},
VectorCodes: []string{"全国行政区.geojson"},
})
if err != nil {
t.Fatalf("create token: %v", err)
}
server, err := New(store, basemap.SystemInfo{
ServiceName: "basemap-pusher",
ServiceVersion: "test",
APIBaseURL: "http://127.0.0.1:8910",
TileBaseURL: "http://127.0.0.1:8910",
VectorBaseURL: "http://127.0.0.1:8910",
SQLitePath: sqlitePath,
ScanRoot: tileRoot,
VectorScanRoot: vectorRoot,
}, Options{})
if err != nil {
t.Fatalf("new server: %v", err)
}
httpServer := httptest.NewServer(server.Handler())
defer httpServer.Close()
response, err := http.Get(httpServer.URL + "/tiles/google_image/0/0/0.webp?token=" + token.Token)
if err != nil {
t.Fatalf("request default tile route: %v", err)
}
defer response.Body.Close()
if response.StatusCode != http.StatusOK {
t.Fatalf("unexpected tile status: %d", response.StatusCode)
}
tileBody, err := io.ReadAll(response.Body)
if err != nil {
t.Fatalf("read tile body: %v", err)
}
if string(tileBody) != "tile" {
t.Fatalf("unexpected tile body: %q", string(tileBody))
}
response, err = http.Get(httpServer.URL + "/geojson/%E5%85%A8%E5%9B%BD%E8%A1%8C%E6%94%BF%E5%8C%BA.geojson?token=" + token.Token)
if err != nil {
t.Fatalf("request geojson route: %v", err)
}
defer response.Body.Close()
if response.StatusCode != http.StatusOK {
t.Fatalf("unexpected geojson status: %d", response.StatusCode)
}
}
@@ -0,0 +1,279 @@
package basemapapi
import (
"context"
"encoding/base64"
"io"
"net/http"
"net/http/httptest"
"net/url"
"os"
"path/filepath"
"strings"
"testing"
"tile-server/api-go/internal/basemap"
)
func newTestStore(t *testing.T, root string) *basemap.Store {
t.Helper()
tileRoot := filepath.Join(root, "tiles")
writeFile(t, filepath.Join(tileRoot, "google_image", "0", "0", "0.webp"), "tile")
vectorRoot := filepath.Join(root, "vectors")
store, err := basemap.OpenStore(basemap.StoreConfig{
SQLitePath: filepath.Join(root, "basemap.db"),
ScanRoot: tileRoot,
VectorScanRoot: vectorRoot,
APIBaseURL: "http://127.0.0.1:8910",
TileBaseURL: "http://127.0.0.1:8910",
VectorBaseURL: "http://127.0.0.1:8910",
})
if err != nil {
t.Fatalf("open store: %v", err)
}
t.Cleanup(func() { _ = store.Close() })
if _, err := store.RunScan(context.Background(), "local-basemaps"); err != nil {
t.Fatalf("run scan: %v", err)
}
return store
}
func writeFile(t *testing.T, path, body string) {
t.Helper()
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
t.Fatalf("mkdir: %v", err)
}
if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
t.Fatalf("write file: %v", err)
}
}
func newTestServer(t *testing.T, store *basemap.Store, options Options) *httptest.Server {
t.Helper()
server, err := New(store, basemap.SystemInfo{ServiceName: "basemap-pusher"}, options)
if err != nil {
t.Fatalf("new server: %v", err)
}
httpServer := httptest.NewServer(server.Handler())
t.Cleanup(httpServer.Close)
return httpServer
}
func basicAuthHeader(user, password string) string {
return "Basic " + base64.StdEncoding.EncodeToString([]byte(user+":"+password))
}
func TestAdminRequiresBasicAuth(t *testing.T) {
store := newTestStore(t, t.TempDir())
httpServer := newTestServer(t, store, Options{Admin: AdminAuth{User: "ops", Password: "s3cret"}})
for _, path := range []string{"/api/v1/admin/basemaps", "/admin/"} {
response, err := http.Get(httpServer.URL + path)
if err != nil {
t.Fatalf("unauthorized GET %s: %v", path, err)
}
response.Body.Close()
if response.StatusCode != http.StatusUnauthorized {
t.Fatalf("expected 401 for anonymous %s, got %d", path, response.StatusCode)
}
request, err := http.NewRequest(http.MethodGet, httpServer.URL+path, nil)
if err != nil {
t.Fatalf("build request: %v", err)
}
request.Header.Set("Authorization", basicAuthHeader("ops", "s3cret"))
response, err = http.DefaultClient.Do(request)
if err != nil {
t.Fatalf("authorized GET %s: %v", path, err)
}
response.Body.Close()
if response.StatusCode != http.StatusOK {
t.Fatalf("expected 200 for authorized %s, got %d", path, response.StatusCode)
}
}
}
func TestAdminRejectsWrongBasicAuth(t *testing.T) {
store := newTestStore(t, t.TempDir())
httpServer := newTestServer(t, store, Options{Admin: AdminAuth{User: "ops", Password: "s3cret"}})
request, _ := http.NewRequest(http.MethodGet, httpServer.URL+"/api/v1/admin/basemaps", nil)
request.Header.Set("Authorization", basicAuthHeader("ops", "wrong"))
response, err := http.DefaultClient.Do(request)
if err != nil {
t.Fatalf("request: %v", err)
}
defer response.Body.Close()
if response.StatusCode != http.StatusUnauthorized {
t.Fatalf("expected 401, got %d", response.StatusCode)
}
}
func TestAdminAcceptsBearerToken(t *testing.T) {
store := newTestStore(t, t.TempDir())
httpServer := newTestServer(t, store, Options{Admin: AdminAuth{Token: "admin-token"}})
request, _ := http.NewRequest(http.MethodGet, httpServer.URL+"/api/v1/admin/basemaps", nil)
request.Header.Set("Authorization", "Bearer admin-token")
response, err := http.DefaultClient.Do(request)
if err != nil {
t.Fatalf("request: %v", err)
}
response.Body.Close()
if response.StatusCode != http.StatusOK {
t.Fatalf("expected 200 with bearer token, got %d", response.StatusCode)
}
request, _ = http.NewRequest(http.MethodGet, httpServer.URL+"/api/v1/admin/basemaps", nil)
request.Header.Set("Authorization", "Bearer nope")
response, err = http.DefaultClient.Do(request)
if err != nil {
t.Fatalf("request: %v", err)
}
response.Body.Close()
if response.StatusCode != http.StatusUnauthorized {
t.Fatalf("expected 401 with a wrong bearer token, got %d", response.StatusCode)
}
}
func TestAdminOpenWhenUnconfigured(t *testing.T) {
store := newTestStore(t, t.TempDir())
httpServer := newTestServer(t, store, Options{})
response, err := http.Get(httpServer.URL + "/api/v1/admin/basemaps")
if err != nil {
t.Fatalf("request: %v", err)
}
defer response.Body.Close()
if response.StatusCode != http.StatusOK {
t.Fatalf("expected the admin API to be open without credentials, got %d", response.StatusCode)
}
}
func TestCatalogStillRequiresTokenEvenWithAdminAuth(t *testing.T) {
store := newTestStore(t, t.TempDir())
httpServer := newTestServer(t, store, Options{Admin: AdminAuth{User: "ops", Password: "s3cret"}})
response, err := http.Get(httpServer.URL + "/api/v1/catalog/basemaps")
if err != nil {
t.Fatalf("request: %v", err)
}
defer response.Body.Close()
if response.StatusCode != http.StatusUnauthorized {
t.Fatalf("expected the catalog to still require a service token, got %d", response.StatusCode)
}
}
func TestCORSAllowlist(t *testing.T) {
store := newTestStore(t, t.TempDir())
httpServer := newTestServer(t, store, Options{CORSAllowedOrigins: []string{"https://maps.example.com"}})
allowed, _ := http.NewRequest(http.MethodGet, httpServer.URL+"/health", nil)
allowed.Header.Set("Origin", "https://maps.example.com")
response, err := http.DefaultClient.Do(allowed)
if err != nil {
t.Fatalf("allowed origin: %v", err)
}
response.Body.Close()
if got := response.Header.Get("Access-Control-Allow-Origin"); got != "https://maps.example.com" {
t.Fatalf("expected the allowlisted origin to be reflected, got %q", got)
}
blocked, _ := http.NewRequest(http.MethodGet, httpServer.URL+"/health", nil)
blocked.Header.Set("Origin", "https://evil.example.com")
response, err = http.DefaultClient.Do(blocked)
if err != nil {
t.Fatalf("blocked origin: %v", err)
}
response.Body.Close()
if got := response.Header.Get("Access-Control-Allow-Origin"); got != "" {
t.Fatalf("expected no CORS header for an unlisted origin, got %q", got)
}
}
func TestCreateTokenFormKeepsTokenOutOfURL(t *testing.T) {
store := newTestStore(t, t.TempDir())
httpServer := newTestServer(t, store, Options{})
form := url.Values{}
form.Set("name", "console")
form.Set("basemap_codes", "google_image")
request, err := http.NewRequest(http.MethodPost, httpServer.URL+"/admin/tokens", strings.NewReader(form.Encode()))
if err != nil {
t.Fatalf("build request: %v", err)
}
request.Header.Set("Content-Type", "application/x-www-form-urlencoded")
client := &http.Client{CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
response, err := client.Do(request)
if err != nil {
t.Fatalf("post form: %v", err)
}
defer response.Body.Close()
body, _ := io.ReadAll(response.Body)
if location := response.Header.Get("Location"); strings.Contains(location, "bmp_") {
t.Fatalf("token leaked into the redirect URL: %s", location)
}
if !strings.Contains(string(body), "bmp_") {
t.Fatalf("expected the new token to be rendered in the response body")
}
}
func TestMetricsEndpointCountsTileMisses(t *testing.T) {
store := newTestStore(t, t.TempDir())
httpServer := newTestServer(t, store, Options{})
created, err := store.CreateToken(context.Background(), basemap.CreateTokenInput{
Name: "metrics",
BasemapCodes: []string{"google_image"},
})
if err != nil {
t.Fatalf("create token: %v", err)
}
response, err := http.Get(httpServer.URL + "/tiles/google_image/current/9/9/9.png?token=" + created.Token)
if err != nil {
t.Fatalf("tile request: %v", err)
}
response.Body.Close()
if response.StatusCode != http.StatusNotFound {
t.Fatalf("expected 404 for a missing tile, got %d", response.StatusCode)
}
response, err = http.Get(httpServer.URL + "/metrics")
if err != nil {
t.Fatalf("metrics request: %v", err)
}
defer response.Body.Close()
body, _ := io.ReadAll(response.Body)
text := string(body)
for _, expected := range []string{
"basemap_pusher_requests_total",
"basemap_pusher_tile_requests_total 1",
"basemap_pusher_tile_misses_total 1",
} {
if !strings.Contains(text, expected) {
t.Fatalf("expected /metrics to contain %q, got:\n%s", expected, text)
}
}
}
func TestScanErrorStatusMapping(t *testing.T) {
cases := []struct {
err error
want int
}{
{basemap.ErrScanInProgress, http.StatusConflict},
{basemap.ErrScanSourceNotFound, http.StatusNotFound},
{basemap.ErrScanSourceDisabled, http.StatusBadRequest},
{io.ErrUnexpectedEOF, http.StatusInternalServerError},
}
for _, tc := range cases {
if got := scanErrorStatus(tc.err); got != tc.want {
t.Fatalf("scanErrorStatus(%v) = %d, want %d", tc.err, got, tc.want)
}
}
}
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,181 @@
package basemapapi
import (
"bytes"
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"testing"
"tile-server/api-go/internal/basemap"
)
func newSliceServer(t *testing.T) (*basemap.Store, *httptest.Server) {
t.Helper()
root := t.TempDir()
tileRoot := filepath.Join(root, "tiles")
if err := os.MkdirAll(tileRoot, 0o755); err != nil {
t.Fatalf("mkdir tile root: %v", err)
}
source := filepath.Join(root, "input.tif")
writeFile(t, source, "fake raster")
// A scanned basemap gives the negative test case something to grant.
writeFile(t, filepath.Join(tileRoot, "google_image", "0", "0", "0.webp"), "tile")
store, err := basemap.OpenStore(basemap.StoreConfig{
SQLitePath: filepath.Join(root, "basemap.db"),
ScanRoot: tileRoot,
VectorScanRoot: filepath.Join(root, "vectors"),
APIBaseURL: "http://127.0.0.1:8910",
TileBaseURL: "http://127.0.0.1:8910",
VectorBaseURL: "http://127.0.0.1:8910",
TileJobCommand: "definitely-not-a-real-binary {input} {output}",
})
if err != nil {
t.Fatalf("open store: %v", err)
}
t.Cleanup(func() { _ = store.Close() })
if _, err := store.RunScan(context.Background(), "local-basemaps"); err != nil {
t.Fatalf("scan: %v", err)
}
return store, newTestServerRaw(t, store)
}
func newTestServerRaw(t *testing.T, store *basemap.Store) *httptest.Server {
t.Helper()
server, err := New(store, basemap.SystemInfo{ServiceName: "basemap-pusher"}, Options{})
if err != nil {
t.Fatalf("new server: %v", err)
}
httpServer := httptest.NewServer(server.Handler())
t.Cleanup(httpServer.Close)
return httpServer
}
func postJob(t *testing.T, url, token string, body map[string]any) *http.Response {
t.Helper()
encoded, err := json.Marshal(body)
if err != nil {
t.Fatalf("marshal: %v", err)
}
request, err := http.NewRequest(http.MethodPost, url, bytes.NewReader(encoded))
if err != nil {
t.Fatalf("request: %v", err)
}
request.Header.Set("Content-Type", "application/json")
request.Header.Set("Authorization", "Bearer "+token)
response, err := http.DefaultClient.Do(request)
if err != nil {
t.Fatalf("post: %v", err)
}
return response
}
func TestSliceJobRequiresSliceScope(t *testing.T) {
ctx := context.Background()
store, httpServer := newSliceServer(t)
source := filepath.Join(filepath.Dir(store.ScanRoot()), "input.tif")
readOnly, err := store.CreateToken(ctx, basemap.CreateTokenInput{
Name: "read-only",
BasemapCodes: []string{"google_image"},
Scopes: []string{"read"},
})
if err != nil {
t.Fatalf("create read-only token: %v", err)
}
if _, err := store.CreateToken(ctx, basemap.CreateTokenInput{Name: "empty"}); err == nil {
t.Fatal("expected a token with neither grants nor slice scope to be rejected")
}
response := postJob(t, httpServer.URL+"/api/v1/slice/jobs", readOnly.Token, map[string]any{
"source_path": source,
"target_code": "demo",
})
response.Body.Close()
if response.StatusCode != http.StatusForbidden {
t.Fatalf("expected 403 for a read-only token, got %d", response.StatusCode)
}
}
func TestSliceJobSubmitAndPoll(t *testing.T) {
ctx := context.Background()
store, httpServer := newSliceServer(t)
source := filepath.Join(filepath.Dir(store.ScanRoot()), "input.tif")
slicer, err := store.CreateToken(ctx, basemap.CreateTokenInput{
Name: "integration",
Scopes: []string{"slice"},
})
if err != nil {
t.Fatalf("create slicer token: %v", err)
}
body := map[string]any{
"code": "integration-job",
"source_path": source,
"target_code": "demo",
"zoom_min": 0,
"zoom_max": 2,
}
response := postJob(t, httpServer.URL+"/api/v1/slice/jobs", slicer.Token, body)
if response.StatusCode != http.StatusAccepted {
response.Body.Close()
t.Fatalf("expected 202, got %d", response.StatusCode)
}
var job basemap.TileJob
if err := json.NewDecoder(response.Body).Decode(&job); err != nil {
t.Fatalf("decode: %v", err)
}
response.Body.Close()
// Re-submitting the same code must not queue a second job.
again := postJob(t, httpServer.URL+"/api/v1/slice/jobs", slicer.Token, body)
again.Body.Close()
if again.StatusCode != http.StatusAccepted {
t.Fatalf("expected the repeat submit to be accepted, got %d", again.StatusCode)
}
request, _ := http.NewRequest(http.MethodGet, httpServer.URL+"/api/v1/slice/jobs/"+job.ID, nil)
request.Header.Set("Authorization", "Bearer "+slicer.Token)
polled, err := http.DefaultClient.Do(request)
if err != nil {
t.Fatalf("poll: %v", err)
}
defer polled.Body.Close()
if polled.StatusCode != http.StatusOK {
t.Fatalf("expected 200 from the poll endpoint, got %d", polled.StatusCode)
}
var fetched basemap.TileJob
if err := json.NewDecoder(polled.Body).Decode(&fetched); err != nil {
t.Fatalf("decode polled job: %v", err)
}
if fetched.ID != job.ID {
t.Fatalf("polled %s, submitted %s", fetched.ID, job.ID)
}
jobs, err := store.ListTileJobs(ctx, 10)
if err != nil {
t.Fatalf("list: %v", err)
}
if len(jobs) != 1 {
t.Fatalf("expected one job after a repeated submit, got %d", len(jobs))
}
}
func TestSliceJobRejectsAnonymous(t *testing.T) {
_, httpServer := newSliceServer(t)
request, _ := http.NewRequest(http.MethodGet, httpServer.URL+"/api/v1/slice/jobs/whatever", nil)
response, err := http.DefaultClient.Do(request)
if err != nil {
t.Fatalf("request: %v", err)
}
defer response.Body.Close()
if response.StatusCode != http.StatusUnauthorized {
t.Fatalf("expected 401 without a token, got %d", response.StatusCode)
}
}