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_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) + } +} 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) {