From 51770298cf0fa7479aa30e01e8f427a867a74fb0 Mon Sep 17 00:00:00 2001 From: Esteban Zimanyi Date: Thu, 19 Nov 2026 11:35:27 +0100 Subject: [PATCH] State the surface of the service route by route api/surface.json is the surface of the service: for every operation the route table holds, its method and path, the conformance class it is a requirement of or that it is an extension, and the functions MobilityDB declares that its handler applies. A server has no object layer for a binding's matrix to read, so the service states its surface itself. ats_surface_test.go writes it and holds it to the code. The functions of a route are read from the source: every SQL call in a string literal its handler reaches, through the package functions and variables it names (tProps among them, whose expressions the query route applies), kept to the names the generated tables state MobilityDB declares. The route table and the router name every handler and answer nothing, so the walk does not enter them. A handler is the innermost named function of its runtime name, since Go names the closure edrQuery returns, inlined into routeTable, routeTable.edrQuery.func1. go test -run TestSurfaceIsWhatTheServiceApplies -update-surface rewrites the file. Measured. go test passes; the 45 routes reach the functions their handlers apply (the TemporalGeometrySequence asMFJSON over sequenceN, the query route interp, cumulativeLength and speed, the coverage rasterUnion, each EDR query asCoverageJSON), the health check none; a surface with one function removed fails the test. --- api/surface.json | 390 ++++++++++++++++++++++++++++++++++++++++++++ ats_surface_test.go | 269 ++++++++++++++++++++++++++++++ 2 files changed, 659 insertions(+) create mode 100644 api/surface.json create mode 100644 ats_surface_test.go diff --git a/api/surface.json b/api/surface.json new file mode 100644 index 0000000..6f77648 --- /dev/null +++ b/api/surface.json @@ -0,0 +1,390 @@ +[ + { + "method": "GET", + "path": "/", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/core", + "functions": [] + }, + { + "method": "GET", + "path": "/api", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/core", + "functions": [] + }, + { + "method": "GET", + "path": "/collections", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/mf-collection", + "functions": [] + }, + { + "method": "POST", + "path": "/collections", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/mf-collection", + "functions": [ + "SRID" + ] + }, + { + "method": "DELETE", + "path": "/collections/{cid}", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/mf-collection", + "functions": [] + }, + { + "method": "GET", + "path": "/collections/{cid}", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/mf-collection", + "functions": [ + "extent", + "stbox", + "transform" + ] + }, + { + "method": "PUT", + "path": "/collections/{cid}", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/mf-collection", + "functions": [] + }, + { + "method": "GET", + "path": "/collections/{cid}/area", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-edr-1/1.1/conf/core", + "functions": [ + "SRID", + "asCoverageJSON", + "clip", + "extent", + "rasterUnion", + "stbox", + "timeSpan", + "transform" + ] + }, + { + "method": "POST", + "path": "/collections/{cid}/bulk", + "extension": true, + "functions": [ + "appendInstant" + ] + }, + { + "method": "GET", + "path": "/collections/{cid}/corridor", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-edr-1/1.1/conf/core", + "functions": [ + "SRID", + "asCoverageJSON", + "clip", + "extent", + "rasterUnion", + "stbox", + "timeSpan", + "transform" + ] + }, + { + "method": "GET", + "path": "/collections/{cid}/coverage", + "conformanceClass": "https://www.opengis.net/spec/ogcapi-coverages-1/1.0/conf/core", + "functions": [ + "SRID", + "clip", + "numBands", + "rasterUnion", + "stbox", + "transform" + ] + }, + { + "method": "GET", + "path": "/collections/{cid}/export", + "extension": true, + "functions": [ + "asBinary", + "asMFJSON", + "atTime", + "eIntersects", + "stbox" + ] + }, + { + "method": "GET", + "path": "/collections/{cid}/items", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures", + "functions": [ + "asMFJSON", + "atTime", + "eIntersects", + "stbox" + ] + }, + { + "method": "POST", + "path": "/collections/{cid}/items", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures", + "functions": [ + "setSRID" + ] + }, + { + "method": "DELETE", + "path": "/collections/{cid}/items/{fid}", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures", + "functions": [] + }, + { + "method": "GET", + "path": "/collections/{cid}/items/{fid}", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures", + "functions": [ + "asMFJSON", + "trajectory" + ] + }, + { + "method": "PUT", + "path": "/collections/{cid}/items/{fid}", + "extension": true, + "functions": [ + "setSRID" + ] + }, + { + "method": "GET", + "path": "/collections/{cid}/items/{fid}/tgsequence", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures", + "functions": [ + "asMFJSON", + "atTime", + "numSequences", + "sequenceN" + ] + }, + { + "method": "POST", + "path": "/collections/{cid}/items/{fid}/tgsequence", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures", + "functions": [ + "merge", + "setSRID" + ] + }, + { + "method": "GET", + "path": "/collections/{cid}/items/{fid}/tgsequence/queries", + "extension": true, + "functions": [] + }, + { + "method": "POST", + "path": "/collections/{cid}/items/{fid}/tgsequence/queries", + "extension": true, + "functions": [ + "asMFJSON", + "transform" + ] + }, + { + "method": "DELETE", + "path": "/collections/{cid}/items/{fid}/tgsequence/queries/{qid}", + "extension": true, + "functions": [] + }, + { + "method": "GET", + "path": "/collections/{cid}/items/{fid}/tgsequence/queries/{qid}", + "extension": true, + "functions": [] + }, + { + "method": "GET", + "path": "/collections/{cid}/items/{fid}/tgsequence/queries/{qid}/stream", + "extension": true, + "functions": [] + }, + { + "method": "DELETE", + "path": "/collections/{cid}/items/{fid}/tgsequence/{tgid}", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures", + "functions": [ + "deleteTime", + "getTime", + "numSequences", + "sequenceN" + ] + }, + { + "method": "GET", + "path": "/collections/{cid}/items/{fid}/tgsequence/{tgid}/{qtype}", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures", + "functions": [ + "asMFJSON", + "atTime", + "cumulativeLength", + "interp", + "numSequences", + "sequenceN", + "speed", + "timeSpan", + "transform" + ] + }, + { + "method": "GET", + "path": "/collections/{cid}/items/{fid}/tproperties", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures", + "functions": [] + }, + { + "method": "POST", + "path": "/collections/{cid}/items/{fid}/tproperties", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures", + "functions": [] + }, + { + "method": "DELETE", + "path": "/collections/{cid}/items/{fid}/tproperties/{pname}", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures", + "functions": [] + }, + { + "method": "GET", + "path": "/collections/{cid}/items/{fid}/tproperties/{pname}", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures", + "functions": [ + "asMFJSON", + "atTime" + ] + }, + { + "method": "POST", + "path": "/collections/{cid}/items/{fid}/tproperties/{pname}", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures", + "functions": [ + "merge" + ] + }, + { + "method": "POST", + "path": "/collections/{cid}/items/{fid}/tproperties/{pname}/ingest", + "extension": true, + "functions": [] + }, + { + "method": "GET", + "path": "/collections/{cid}/items/{fid}/tproperties/{pname}/queries", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-4/1.0/conf/cquery", + "functions": [] + }, + { + "method": "POST", + "path": "/collections/{cid}/items/{fid}/tproperties/{pname}/queries", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-4/1.0/conf/cquery", + "functions": [ + "asMFJSON" + ] + }, + { + "method": "DELETE", + "path": "/collections/{cid}/items/{fid}/tproperties/{pname}/queries/{qid}", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-4/1.0/conf/cquery", + "functions": [] + }, + { + "method": "GET", + "path": "/collections/{cid}/items/{fid}/tproperties/{pname}/queries/{qid}", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-4/1.0/conf/cquery", + "functions": [] + }, + { + "method": "GET", + "path": "/collections/{cid}/items/{fid}/tproperties/{pname}/queries/{qid}/stream", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-4/1.0/conf/cquery", + "functions": [] + }, + { + "method": "DELETE", + "path": "/collections/{cid}/items/{fid}/tproperties/{pname}/{tvid}", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures", + "functions": [ + "deleteTime", + "getTime", + "numSequences", + "sequenceN" + ] + }, + { + "method": "GET", + "path": "/collections/{cid}/position", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-edr-1/1.1/conf/core", + "functions": [ + "SRID", + "asCoverageJSON", + "clip", + "extent", + "rasterUnion", + "stbox", + "timeSpan", + "transform" + ] + }, + { + "method": "GET", + "path": "/collections/{cid}/schema", + "conformanceClass": "https://www.opengis.net/spec/ogcapi-coverages-1/1.0/conf/core", + "functions": [ + "bandPixelType", + "numBands" + ] + }, + { + "method": "GET", + "path": "/collections/{cid}/timeseries", + "extension": true, + "functions": [ + "asMFJSON", + "tsample" + ] + }, + { + "method": "GET", + "path": "/collections/{cid}/trajectories", + "extension": true, + "functions": [ + "asMFJSON", + "numInstants", + "transform", + "tsample" + ] + }, + { + "method": "GET", + "path": "/collections/{cid}/trajectory", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-edr-1/1.1/conf/core", + "functions": [ + "SRID", + "asCoverageJSON", + "clip", + "extent", + "rasterUnion", + "stbox", + "timeSpan", + "transform" + ] + }, + { + "method": "GET", + "path": "/conformance", + "conformanceClass": "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/core", + "functions": [] + }, + { + "method": "GET", + "path": "/health", + "extension": true, + "functions": [] + } +] diff --git a/ats_surface_test.go b/ats_surface_test.go new file mode 100644 index 0000000..59e9b22 --- /dev/null +++ b/ats_surface_test.go @@ -0,0 +1,269 @@ +// The surface of the service, route by route: for every operation #routeTable +// holds, the conformance class it is a requirement of or that it is an +// extension, and the functions MobilityDB declares that its handler applies. +// +// A binding states its surface by its object layer; MobilityAPI has none, so it +// states its surface here, in api/surface.json, which this file writes and +// holds to the code. The functions of a route are read from the source: every +// SQL call in a string literal its handler reaches, through the package +// functions it calls, kept to the names the generated tables state MobilityDB +// declares (#temporalTypes, #rasterTypes, #boxFunctions, #mathOps). A route +// whose handler reaches a branch applies every function of that branch, so the +// list is what the route can apply. A name the handler builds at run time from +// the generated tables, the MF-JSON reader FromMFJSON of a collection's +// type, is the type's and is read from #temporalTypes, not from this list. +// +// Regenerate after a change to a route or a handler: +// +// go test -run TestSurfaceIsWhatTheServiceApplies -update-surface . +package main + +import ( + "bytes" + "encoding/json" + "flag" + "go/ast" + "go/parser" + "go/token" + "os" + "path/filepath" + "reflect" + "regexp" + "runtime" + "sort" + "strconv" + "strings" + "testing" +) + +const surfacePath = "api/surface.json" + +var updateSurface = flag.Bool("update-surface", false, "write "+surfacePath+" from the code") + +// surfaceRoute is one operation of the surface. +type surfaceRoute struct { + Method string `json:"method"` + Path string `json:"path"` + Class string `json:"conformanceClass,omitempty"` + Extension bool `json:"extension,omitempty"` + Functions []string `json:"functions"` +} + +// declaredFunctions answers the functions the generated tables state MobilityDB +// declares, keyed by their lower-case name, valued by the catalog's spelling. +func declaredFunctions() map[string]string { + out := map[string]string{} + add := func(n string) { out[strings.ToLower(n)] = n } + for _, t := range temporalTypes { + for _, f := range t.Funcs { + add(f) + } + } + for _, t := range rasterTypes { + for _, f := range t.Funcs { + add(f) + } + } + for _, fs := range boxFunctions { + for _, f := range fs { + add(f) + } + } + for _, m := range mathOps { + add(m.SQLName) + } + return out +} + +// packageSource parses the non-test Go files of the package and answers each +// top-level function and each package variable by name: a handler takes SQL from +// its own literals and from tables such as tProps, whose expressions it applies. +func packageSource(t *testing.T) map[string]ast.Node { + t.Helper() + files, err := filepath.Glob("*.go") + if err != nil { + t.Fatal(err) + } + fset := token.NewFileSet() + out := map[string]ast.Node{} + for _, f := range files { + if strings.HasSuffix(f, "_test.go") { + continue + } + file, err := parser.ParseFile(fset, f, nil, parser.SkipObjectResolution) + if err != nil { + t.Fatal(err) + } + for _, d := range file.Decls { + switch v := d.(type) { + case *ast.FuncDecl: + if v.Recv == nil { + out[v.Name.Name] = v + } + case *ast.GenDecl: + if v.Tok != token.VAR { + continue + } + for _, spec := range v.Specs { + vs := spec.(*ast.ValueSpec) + for _, n := range vs.Names { + out[n.Name] = vs + } + } + } + } + } + return out +} + +// sqlCall matches a call in SQL text: a name followed by its opening parenthesis. +var sqlCall = regexp.MustCompile(`([A-Za-z_][A-Za-z0-9_]*)\(`) + +// routingFunctions are the functions that route requests rather than answer them. +var routingFunctions = map[string]bool{"routeTable": true, "newMux": true} + +// handlerName answers the function a handler is, or is a closure of. Go names a +// closure after every function enclosing it, the ones inlined into its caller +// among them (routeTable.edrQuery.func1 for the closure edrQuery returns, inlined +// into routeTable), so the handler is the innermost named function. +func handlerName(h any) string { + full := runtime.FuncForPC(reflect.ValueOf(h).Pointer()).Name() + parts := strings.Split(full[strings.LastIndex(full, "/")+1:], ".")[1:] + for len(parts) > 1 && closureName.MatchString(parts[len(parts)-1]) { + parts = parts[:len(parts)-1] + } + return parts[len(parts)-1] +} + +// closureName matches the name Go gives an anonymous function, func1, func2, ... +var closureName = regexp.MustCompile(`^func\d+$`) + +// reachedFunctions answers the declared functions the SQL literals reachable from +// the function root apply, following the package functions and variables it +// names. +func reachedFunctions(decls map[string]ast.Node, declared map[string]string, root string) []string { + seen := map[string]bool{} + found := map[string]bool{} + var visit func(name string) + visit = func(name string) { + fd, ok := decls[name] + if !ok || seen[name] { + return + } + seen[name] = true + ast.Inspect(fd, func(n ast.Node) bool { + switch v := n.(type) { + case *ast.BasicLit: + if v.Kind == token.STRING { + s, err := strconv.Unquote(v.Value) + if err != nil { + return true + } + for _, m := range sqlCall.FindAllStringSubmatch(s, -1) { + if spelled, ok := declared[strings.ToLower(m[1])]; ok { + found[spelled] = true + } + } + } + case *ast.Ident: + // A package function or variable named here. The + // route table and the router name every handler and apply none, so + // the walk does not enter them: the API definition reads the table + // to mark its operations and applies nothing the routes apply. + if _, ok := decls[v.Name]; ok && !routingFunctions[v.Name] { + visit(v.Name) + } + } + return true + }) + } + visit(root) + out := make([]string, 0, len(found)) + for f := range found { + out = append(out, f) + } + sort.Strings(out) + return out +} + +// surface builds the surface of the service from the route table and the source. +func surface(t *testing.T) []surfaceRoute { + t.Helper() + decls := packageSource(t) + declared := declaredFunctions() + var out []surfaceRoute + for _, r := range routeTable() { + root := handlerName(r.handler) + if _, ok := decls[root]; !ok || routingFunctions[root] { + t.Fatalf("%s %s: its handler resolves to %s, which is no handler of the package source", + r.method, r.path, root) + } + s := surfaceRoute{Method: r.method, Path: r.path, Class: r.class, Extension: r.class == extension, + Functions: reachedFunctions(decls, declared, root)} + out = append(out, s) + } + sort.Slice(out, func(i, j int) bool { + if out[i].Path != out[j].Path { + return out[i].Path < out[j].Path + } + return out[i].Method < out[j].Method + }) + return out +} + +// The committed surface is what the code applies; -update-surface rewrites it. +func TestSurfaceIsWhatTheServiceApplies(t *testing.T) { + b, err := json.MarshalIndent(surface(t), "", " ") + if err != nil { + t.Fatal(err) + } + b = append(b, '\n') + if *updateSurface { + if err := os.WriteFile(surfacePath, b, 0o644); err != nil { + t.Fatal(err) + } + return + } + committed, err := os.ReadFile(surfacePath) + if err != nil { + t.Fatalf("%v: write it with go test -run TestSurfaceIsWhatTheServiceApplies -update-surface .", err) + } + if !bytes.Equal(committed, b) { + t.Errorf("%s is not what the code applies; rewrite it with "+ + "go test -run TestSurfaceIsWhatTheServiceApplies -update-surface .", surfacePath) + } +} + +// The reading finds what a handler is known to apply: the TemporalGeometrySequence +// is written by asMFJSON over sequenceN, the coverage by the raster writers, and +// the health check applies nothing. +func TestSurfaceReadsKnownHandlers(t *testing.T) { + byKey := map[string][]string{} + for _, s := range surface(t) { + byKey[s.Method+" "+s.Path] = s.Functions + } + has := func(key, fn string) bool { + for _, f := range byKey[key] { + if f == fn { + return true + } + } + return false + } + for _, c := range []struct{ key, fn string }{ + {"GET /collections/{cid}/items/{fid}/tgsequence", "asMFJSON"}, + {"GET /collections/{cid}/items/{fid}/tgsequence", "sequenceN"}, + {"GET /collections/{cid}/items/{fid}/tgsequence/{tgid}/{qtype}", "interp"}, + {"GET /collections/{cid}/items/{fid}/tgsequence/{tgid}/{qtype}", "cumulativeLength"}, + {"GET /collections/{cid}/items/{fid}/tgsequence/{tgid}/{qtype}", "speed"}, + {"GET /collections/{cid}/coverage", "rasterUnion"}, + {"GET /collections/{cid}/position", "asCoverageJSON"}, + } { + if !has(c.key, c.fn) { + t.Errorf("%s does not list %s, which its handler applies: %v", c.key, c.fn, byKey[c.key]) + } + } + if fs := byKey["GET /health"]; len(fs) != 0 { + t.Errorf("GET /health lists %v, though it applies no function", fs) + } +}