Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions api/surface.json
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,9 @@
"asCoverageJSON",
"clip",
"extent",
"rasterTileValue",
"rasterUnion",
"rasterValue",
"stbox",
"timeSpan",
"transform"
Expand All @@ -79,7 +81,9 @@
"asCoverageJSON",
"clip",
"extent",
"rasterTileValue",
"rasterUnion",
"rasterValue",
"stbox",
"timeSpan",
"transform"
Expand All @@ -91,6 +95,8 @@
"conformanceClass": "https://www.opengis.net/spec/ogcapi-coverages-1/1.0/conf/core",
"functions": [
"SRID",
"asCoverageJSON",
"asTIFF",
"clip",
"numBands",
"rasterUnion",
Expand Down Expand Up @@ -226,6 +232,8 @@
"cumulativeLength",
"interp",
"numSequences",
"rasterTileValue",
"rasterValue",
"sequenceN",
"speed",
"timeSpan",
Expand Down Expand Up @@ -325,7 +333,9 @@
"asCoverageJSON",
"clip",
"extent",
"rasterTileValue",
"rasterUnion",
"rasterValue",
"stbox",
"timeSpan",
"transform"
Expand Down Expand Up @@ -369,7 +379,9 @@
"asCoverageJSON",
"clip",
"extent",
"rasterTileValue",
"rasterUnion",
"rasterValue",
"stbox",
"timeSpan",
"transform"
Expand Down
189 changes: 189 additions & 0 deletions ats_surface_catalog_test.go
Original file line number Diff line number Diff line change
@@ -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<Format> or a reader <type>From<Format>.
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)
}
}
97 changes: 81 additions & 16 deletions ats_surface_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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 {
Expand All @@ -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)
Expand Down Expand Up @@ -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) {
Expand Down