From c270dd89730ad7ff41919aedf992fa4e52fb5534 Mon Sep 17 00:00:00 2001 From: Esteban Zimanyi Date: Thu, 19 Nov 2026 12:19:46 +0100 Subject: [PATCH 1/2] Read the function a handler names at run time through a catalog gate A handler that picks a function by name at run time passes the name through a catalog gate (typeHas, boxHas, rasterHas, needRaster) before applying it, as the raster query picks rasterValue or rasterTileValue and the coverage its negotiated writer. Below a function that calls a gate, the surface reads a string literal that is a function's bare name as that function, besides the calls it reads everywhere. A bare name that names a type or a resource of the service (raster, stbox, the EDR query trajectory) is read as such, both sets taken from the generated tables and the route table. The generated tables are the catalog the gates read and no code a route runs, so the walk does not enter them. Measured. The query route and the four EDR queries gain rasterValue and rasterTileValue, the coverage asCoverageJSON and asTIFF, and no other route changes; go test passes. --- api/surface.json | 12 ++++++ ats_surface_test.go | 97 +++++++++++++++++++++++++++++++++++++-------- 2 files changed, 93 insertions(+), 16 deletions(-) diff --git a/api/surface.json b/api/surface.json index 6f77648..7acdd3b 100644 --- a/api/surface.json +++ b/api/surface.json @@ -56,7 +56,9 @@ "asCoverageJSON", "clip", "extent", + "rasterTileValue", "rasterUnion", + "rasterValue", "stbox", "timeSpan", "transform" @@ -79,7 +81,9 @@ "asCoverageJSON", "clip", "extent", + "rasterTileValue", "rasterUnion", + "rasterValue", "stbox", "timeSpan", "transform" @@ -91,6 +95,8 @@ "conformanceClass": "https://www.opengis.net/spec/ogcapi-coverages-1/1.0/conf/core", "functions": [ "SRID", + "asCoverageJSON", + "asTIFF", "clip", "numBands", "rasterUnion", @@ -226,6 +232,8 @@ "cumulativeLength", "interp", "numSequences", + "rasterTileValue", + "rasterValue", "sequenceN", "speed", "timeSpan", @@ -325,7 +333,9 @@ "asCoverageJSON", "clip", "extent", + "rasterTileValue", "rasterUnion", + "rasterValue", "stbox", "timeSpan", "transform" @@ -369,7 +379,9 @@ "asCoverageJSON", "clip", "extent", + "rasterTileValue", "rasterUnion", + "rasterValue", "stbox", "timeSpan", "transform" diff --git a/ats_surface_test.go b/ats_surface_test.go index 59e9b22..58580a6 100644 --- a/ats_surface_test.go +++ b/ats_surface_test.go @@ -87,7 +87,10 @@ func packageSource(t *testing.T) map[string]ast.Node { fset := token.NewFileSet() out := map[string]ast.Node{} for _, f := range files { - if strings.HasSuffix(f, "_test.go") { + // The generated tables are the catalog a handler checks a type against + // (typeHas), naming every function by bare name; they are not code a route + // runs, so the walk reads them as the catalog and never as a handler's. + if strings.HasSuffix(f, "_test.go") || strings.HasSuffix(f, "_gen.go") { continue } file, err := parser.ParseFile(fset, f, nil, parser.SkipObjectResolution) @@ -138,20 +141,75 @@ func handlerName(h any) string { // 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. +// catalogGates are the functions by which a handler checks that MobilityDB +// declares a function over a type before applying it (rule 4 of the plan: a +// function MobilityDB declares over no type of the collection is refused by +// name). A handler that picks a function by name at run time, as the raster query +// picks rasterValue or rasterTileValue, passes the name through one of them. +var catalogGates = map[string]bool{"typeHas": true, "boxHas": true, "rasterHas": true, "needRaster": true} + +// callsGate reports whether a declaration calls a catalog gate. +func callsGate(n ast.Node) bool { + found := false + ast.Inspect(n, func(x ast.Node) bool { + if c, ok := x.(*ast.CallExpr); ok { + if id, ok := c.Fun.(*ast.Ident); ok && catalogGates[id.Name] { + found = true + } + } + return !found + }) + return found +} + +// notAFunction are the bare names that name something other than a function the +// handler applies, though MobilityDB declares a function of the same name: a +// type (raster, stbox, tgeompoint), read as the type a handler compares, and a +// resource of the service (the EDR query trajectory), read as the path segment +// the route table gives it. Both sets are read from the code, not listed here. +var notAFunction = func() map[string]bool { + out := map[string]bool{} + for _, t := range temporalTypes { + out[strings.ToLower(t.Name)] = true + } + for _, t := range rasterTypes { + out[strings.ToLower(t.Name)] = true + } + for b := range boxFunctions { + out[strings.ToLower(b)] = true + } + for _, r := range routeTable() { + for _, seg := range strings.Split(r.path, "/") { + if seg != "" && !strings.HasPrefix(seg, "{") { + out[strings.ToLower(seg)] = true + } + } + } + return out +}() + +// reachedFunctions answers the declared functions reachable from the function +// root, following the package functions and variables it names. A function is +// reached when a string literal calls it (name followed by its parenthesis), or, +// below a function that calls a catalog gate, when a string literal is its bare +// name: the name the gate checks and the handler then applies, as the raster +// query applies rasterValue and the coverage its negotiated writer. 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] { + var visit func(name string, gatedCaller bool) + visit = func(name string, gatedCaller bool) { + node, ok := decls[name] + key := name + "/" + strconv.FormatBool(gatedCaller) + if !ok || seen[key] { return } - seen[name] = true - ast.Inspect(fd, func(n ast.Node) bool { + seen[key] = true + gated := gatedCaller + if _, isFunc := node.(*ast.FuncDecl); isFunc { + gated = gatedCaller || callsGate(node) + } + ast.Inspect(node, func(n ast.Node) bool { switch v := n.(type) { case *ast.BasicLit: if v.Kind == token.STRING { @@ -164,20 +222,25 @@ func reachedFunctions(decls map[string]ast.Node, declared map[string]string, roo found[spelled] = true } } + if gated && !notAFunction[strings.ToLower(s)] { + if spelled, ok := declared[strings.ToLower(s)]; 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. + // 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) + visit(v.Name, gated) } } return true }) } - visit(root) + visit(root, false) out := make([]string, 0, len(found)) for f := range found { out = append(out, f) @@ -256,7 +319,9 @@ func TestSurfaceReadsKnownHandlers(t *testing.T) { {"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}/items/{fid}/tgsequence/{tgid}/{qtype}", "rasterValue"}, {"GET /collections/{cid}/coverage", "rasterUnion"}, + {"GET /collections/{cid}/coverage", "asTIFF"}, {"GET /collections/{cid}/position", "asCoverageJSON"}, } { if !has(c.key, c.fn) { From ae4a8bbe92d116e435474cbb934deb2411e3b1c7 Mon Sep 17 00:00:00 2001 From: Esteban Zimanyi Date: Thu, 19 Nov 2026 12:19:54 +0100 Subject: [PATCH 2/2] Read the surface of the service against what MobilityDB declares ats_surface_catalog_test.go reads api/surface.json against the generated tables. A route serves the types of the collections it reads: a Coverages or EDR route a raster collection, a collection-level route (/collections, /collections/{cid}) a collection of either kind, every other route a moving feature's temporal value; each also serves the box and span types, the bounds a query is given and the extent a collection states. Every function a route applies is one MobilityDB states over a type it serves, and the check refuses a raster writer on a moving-feature route and a trajectory function on a raster route. Per spatial temporal type it reports the input and output functions and the raster functions the moving-feature routes reach, and how many routes a collection of the type answers in full, every function they apply being stated over it; a route a type does not answer in full refuses that collection by name. MobilityAPI is measured by this test rather than by the binding matrices of MobilityDB (tools/raster_matrix.py, tools/io_matrix.py), which read an object layer a server has none of. Measured. Every function of the 45 routes is stated over a type its route serves; every spatial type reaches asBinary and asMFJSON, tgeompoint alone the raster readers rasterValue and rasterTileValue, and tgeompoint is answered in full by 18 of the 19 moving-feature routes that apply a function; go test passes. --- ats_surface_catalog_test.go | 189 ++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 ats_surface_catalog_test.go diff --git a/ats_surface_catalog_test.go b/ats_surface_catalog_test.go new file mode 100644 index 0000000..9aeb70f --- /dev/null +++ b/ats_surface_catalog_test.go @@ -0,0 +1,189 @@ +// The surface of the service read against what MobilityDB declares. +// +// api/surface.json states, route by route, the functions each handler applies +// (#TestSurfaceIsWhatTheServiceApplies). This file reads them against the +// generated tables: every function a route applies is one MobilityDB states over +// a type the route serves, and, per temporal type, it reports which raster and +// input and output functions the routes reach and which routes a collection of +// that type answers in full. +// +// A route serves the types of the collections it reads. A Coverages or EDR route +// reads a raster collection, a collection-level route (/collections, +// /collections/{cid}) registers and describes a collection of either kind, and +// every other route reads a moving feature's temporal value. Each also serves +// the box and span types (#boxFunctions), the bounds a query is given and the +// extent a collection states. MobilityAPI is measured here rather than by the +// binding matrices of MobilityDB, which read an object layer a server has none of. +package main + +import ( + "encoding/json" + "os" + "reflect" + "sort" + "strings" + "testing" +) + +// routeServes answers the kinds of collection a route reads: raster, temporal, +// or both. +func routeServes(s surfaceRoute) (temporal, raster bool) { + if s.Path == "/collections" || s.Path == "/collections/{cid}" { + return true, true + } + if strings.HasPrefix(s.Class, coverageConfBase) || s.Class == edrConformance { + return false, true + } + return true, false +} + +// functionsOver answers the functions the generated tables state over the +// temporal types, over the raster types and over the box and span types. +func functionsOver() (temporal, raster, box map[string]bool) { + temporal, raster, box = map[string]bool{}, map[string]bool{}, map[string]bool{} + for _, t := range temporalTypes { + for _, f := range t.Funcs { + temporal[f] = true + } + } + for _, t := range rasterTypes { + for _, f := range t.Funcs { + raster[f] = true + } + } + for b, fs := range boxFunctions { + box[b] = true // the box's own constructor, stbox(trip) + for _, f := range fs { + box[f] = true + } + } + return temporal, raster, box +} + +// committedSurface reads api/surface.json. +func committedSurface(t *testing.T) []surfaceRoute { + t.Helper() + b, err := os.ReadFile(surfacePath) + if err != nil { + t.Fatal(err) + } + var out []surfaceRoute + if err := json.Unmarshal(b, &out); err != nil { + t.Fatal(err) + } + if len(out) == 0 { + t.Fatalf("%s holds no route, so this test would assert nothing", surfacePath) + } + return out +} + +// misplaced answers the functions a route applies that MobilityDB states over no +// type the route serves, reading the types as #routeServes and #functionsOver do. +func misplaced(s surfaceRoute) []string { + temporal, raster, box := functionsOver() + servesTemporal, servesRaster := routeServes(s) + var out []string + for _, f := range s.Functions { + if !box[f] && !(servesTemporal && temporal[f]) && !(servesRaster && raster[f]) { + out = append(out, f) + } + } + return out +} + +// Every function a route applies is one MobilityDB states over a type the route +// serves, over the surface #TestSurfaceIsWhatTheServiceApplies holds to the code. +func TestSurfaceFunctionsAreStatedOverTheServedTypes(t *testing.T) { + var checked int + for _, s := range committedSurface(t) { + checked += len(s.Functions) + if m := misplaced(s); len(m) > 0 { + t.Errorf("%s %s applies %v, which MobilityDB states over no type the route serves", s.Method, s.Path, m) + } + } + if checked == 0 { + t.Fatal("the surface applies no function, so this test would assert nothing") + } +} + +// The check refuses what it exists to refuse, as #TestATSSchemaMotionCurveIsInverted +// pairs a check with the cases it must refuse: a raster writer on a +// moving-feature route, a trajectory function on a raster route, and nothing a +// collection-level route applies to a collection of either kind. +func TestSurfaceMisplacedFunctionsAreFound(t *testing.T) { + for _, c := range []struct { + s surfaceRoute + want []string + }{ + {surfaceRoute{Path: "/collections/{cid}/items", Class: confMovingFeatures, + Functions: []string{"asMFJSON", "asTIFF"}}, []string{"asTIFF"}}, + {surfaceRoute{Path: "/collections/{cid}/coverage", Class: coverageConfBase + "core", + Functions: []string{"asTIFF", "cumulativeLength"}}, []string{"cumulativeLength"}}, + {surfaceRoute{Path: "/collections", Class: confMFCollection, + Functions: []string{"SRID", "setSRID", "stbox"}}, nil}, + } { + if got := misplaced(c.s); !reflect.DeepEqual(got, c.want) { + t.Errorf("%s applying %v: misplaced %v, want %v", c.s.Path, c.s.Functions, got, c.want) + } + } +} + +// isIOFunction reports a function that writes or reads a value in an external +// format: a writer as or a reader From. +func isIOFunction(f string) bool { + return strings.HasPrefix(f, "as") || strings.Contains(f, "From") +} + +// Per temporal type: the raster and input and output functions the moving-feature +// routes reach that MobilityDB states over the type, and the routes a collection +// of the type answers in full, every function they apply being stated over it. +// It is a report: a route a type does not answer in full refuses that collection +// by name (#typeHas), which is what the service states. +func TestSurfacePerCollectionType(t *testing.T) { + _, raster, box := functionsOver() + surface := committedSurface(t) + for _, tt := range temporalTypes { + if !tt.Spatial { + continue + } + has := map[string]bool{} + for _, f := range tt.Funcs { + has[f] = true + } + boxHas := map[string]bool{tt.Box: true} + for _, f := range boxFunctions[tt.Box] { + boxHas[f] = true + } + var io, rasterReached []string + seen := map[string]bool{} + var full, partial int + for _, s := range surface { + if servesTemporal, _ := routeServes(s); !servesTemporal || len(s.Functions) == 0 { + continue + } + answered := true + for _, f := range s.Functions { + answered = answered && (has[f] || boxHas[f]) + if seen[f] || !has[f] { + continue + } + seen[f] = true + if isIOFunction(f) { + io = append(io, f) + } + if raster[f] && !box[f] { + rasterReached = append(rasterReached, f) + } + } + if answered { + full++ + } else { + partial++ + } + } + sort.Strings(io) + sort.Strings(rasterReached) + t.Logf("%-12s routes answered in full %2d, in part %2d; input and output %v; raster %v", + tt.Name, full, partial, io, rasterReached) + } +}