From 6c3f3c5956d5dfefd5ceab726db22ddb7174f81d Mon Sep 17 00:00:00 2001 From: Esteban Zimanyi Date: Thu, 19 Nov 2026 11:30:07 +0100 Subject: [PATCH] Read each requirement of the Part 4 class cquery through the test that states it ats_part4_test.go holds the requirements of the class cquery of OGC API - Moving Features - Part 4 as rows beside the abstract tests of Part 1, keyed by the identifier and number the draft gives them (Req 1 cquery_link, Req 2 window, Req 3 window_tumbling, Req 4 window_hopping, Req 5 window_count), each naming the test that reads the answer it states. The rows are held to CONFORMANCE.md, which records the requirements from the draft MobilityAPI implements, row by row with the test it names, and to the test files. A window result carries the bounds of its window: emitWindow writes [start, end) for a time window, the span boundaries a TUMBLING or HOPPING window covers, and [start, end] for a COUNT window, the times of its first and last record. TestMeosWindowBounds reads them for each kind of window and TestMeosTumblingWindow reads Requirement 3, two consecutive windows of fixed duration that meet. Witness. A window result carried the times of its first and last record whatever its kind: a 3 s tumbling window [00:00, 00:03) over records at 1 s and 2 s reported [00:01, 00:02], a hopping window [-2 s, 1 s) reported [00:00, 00:00], and consecutive tumbling windows did not meet. Requirement 2 was credited to TestWindowResultShape, which built an Event literal and checked the literal's own keys, reading nothing the service writes. Measured. go test passes with and without the meos tag, libmeos built from MobilityDB master 0d5a079d63; on master's engine the two new tests fail on the TUMBLING and HOPPING bounds and pass on COUNT. --- CONFORMANCE.md | 6 +-- ats_part4_test.go | 101 +++++++++++++++++++++++++++++++++++++ stream_conformance_test.go | 17 ------- stream_engine_meos.go | 20 +++++--- stream_meos_test.go | 83 ++++++++++++++++++++++++++++++ 5 files changed, 200 insertions(+), 27 deletions(-) create mode 100644 ats_part4_test.go diff --git a/CONFORMANCE.md b/CONFORMANCE.md index 3d6941d..b434472 100644 --- a/CONFORMANCE.md +++ b/CONFORMANCE.md @@ -12,10 +12,10 @@ http://www.opengis.net/spec/ogcapi-movingfeatures-4/1.0/conf/cquery | Requirement | Status | Where | |---|---|---| | **Req 1** `cquery_link` — the `cquery` link object carries `rel`, `queryId`, `href`, `channel`, `status`, `type` | **met** | `cqueryLink` (`stream.go`); asserted by `TestCqueryLinkShape` | -| **Req 2** `window` — a query carries a `window`; the result carries `[windowStart, windowEnd]` | **met** | `postQuery` window parsing; the meos engine emits the bounds; `TestWindowResultShape` | -| **Req 3** `window_tumbling` — fixed-duration, non-overlapping windows | **met** | `runAggregate` TUMBLING (`stream_engine_meos.go`) | +| **Req 2** `window` — a query carries a `window`; the result carries `[windowStart, windowEnd]`, `[start, end)` for a time window and `[start, end]` for a count window | **met** | `postQuery` window parsing; `emitWindow` (`stream_engine_meos.go`) writes the bounds of the window; `TestMeosWindowBounds` | +| **Req 3** `window_tumbling` — fixed-duration, non-overlapping windows | **met** | `runAggregate` TUMBLING (`stream_engine_meos.go`); `TestMeosTumblingWindow` | | **Req 4** `window_hopping` — fixed-duration, overlapping windows | **met** | `runHopping` (`stream_engine_meos.go`); `TestMeosHoppingWindow` | -| **Req 5** `window_count` — windows over a record count | **met** | `runAggregate` COUNT; `TestMeosWindowAggregate` | +| **Req 5** `window_count` — windows over a record count | **met** | `runAggregate` COUNT (`stream_engine_meos.go`); `TestMeosWindowAggregate` | ## Aggregations diff --git a/ats_part4_test.go b/ats_part4_test.go new file mode 100644 index 0000000..cda4ca7 --- /dev/null +++ b/ats_part4_test.go @@ -0,0 +1,101 @@ +// The requirements of the class cquery of OGC API – Moving Features – Part 4 +// (Stream Extension), as executable rows beside the abstract tests of Part 1. +// +// Part 4 is an unpublished OGC draft that no public repository of OGC holds, and +// what it states no abstract test of; its requirements are the rows, each keyed +// by the identifier the draft gives it and read from CONFORMANCE.md, which +// records them from the draft MobilityAPI implements. A row names the test that +// reads the answer it states, as #atsDischargedBy does for Part 1. +// +// ⛔ THE ROWS FOLLOW THE DRAFT MOBILITYAPI READ. The public summary of a newer +// draft, the FOSS4G workshop of the Moving Features SWG in opengeospatial/mf-swg, +// describes a Continuous Query resource with id, pubtime, target, filter and +// queryResult; once that draft is at hand, these rows and CONFORMANCE.md follow it. +package main + +import ( + "bytes" + "os" + "path/filepath" + "regexp" + "testing" +) + +// atsPart4Req is one requirement of the class cquery. +type atsPart4Req struct { + id string // the draft's identifier, as CONFORMANCE.md writes it + number int // the draft's requirement number + dischargedBy string // the test that reads the answer it states +} + +// atsPart4 is the class cquery, its requirements in the draft's order. +var atsPart4 = []atsPart4Req{ + {"cquery_link", 1, "TestCqueryLinkShape"}, + {"window", 2, "TestMeosWindowBounds"}, + {"window_tumbling", 3, "TestMeosTumblingWindow"}, + {"window_hopping", 4, "TestMeosHoppingWindow"}, + {"window_count", 5, "TestMeosWindowAggregate"}, +} + +// conformanceReq matches a requirement row of CONFORMANCE.md: its number, its +// identifier and the cell naming where it is met. +var conformanceReq = regexp.MustCompile("(?m)^\\| \\*\\*Req (\\d+)\\*\\* `([a-z_]+)`[^|]*\\|[^|]*\\|([^|]*)\\|$") + +// The rows are the requirements CONFORMANCE.md records, each with its number and +// identifier, and the test a row names is the one CONFORMANCE.md names for it. +func TestATSPart4RowsAreTheRecordedRequirements(t *testing.T) { + doc, err := os.ReadFile("CONFORMANCE.md") + if err != nil { + t.Fatal(err) + } + recorded := conformanceReq.FindAllSubmatch(doc, -1) + if len(recorded) == 0 { + t.Fatal("CONFORMANCE.md records no requirement row the pattern reads, so this test would assert nothing") + } + if len(recorded) != len(atsPart4) { + t.Errorf("CONFORMANCE.md records %d requirements of cquery, the rows hold %d", len(recorded), len(atsPart4)) + } + for i, m := range recorded { + if i >= len(atsPart4) { + break + } + row := atsPart4[i] + if string(m[1]) != itoa(row.number) || string(m[2]) != row.id { + t.Errorf("row %d is Req %d %s, CONFORMANCE.md records Req %s %s", i, row.number, row.id, m[1], m[2]) + } + if !bytes.Contains(m[3], []byte("`"+row.dischargedBy+"`")) { + t.Errorf("Req %d %s names %s, which CONFORMANCE.md does not name where it is met: %s", + row.number, row.id, row.dischargedBy, bytes.TrimSpace(m[3])) + } + } +} + +// Every row names a test a test file declares, whatever build tag it runs under: +// the window requirements are read through the MEOS engine, which the conformance +// job builds with the meos tag. +func TestATSPart4RowsAreDischarged(t *testing.T) { + files, err := filepath.Glob("*_test.go") + if err != nil { + t.Fatal(err) + } + var src []byte + for _, f := range files { + b, err := os.ReadFile(f) + if err != nil { + t.Fatal(err) + } + src = append(src, b...) + } + for _, r := range atsPart4 { + if !bytes.Contains(src, []byte("func "+r.dischargedBy+"(")) { + t.Errorf("Req %d %s names %s, which no test file declares", r.number, r.id, r.dischargedBy) + } + } +} + +// The class the rows belong to is one the service declares. +func TestATSPart4ClassIsDeclared(t *testing.T) { + if !declaredClasses(t)[confCQuery] { + t.Errorf("the conformance declaration does not list %s, whose requirements these rows are", confCQuery) + } +} diff --git a/stream_conformance_test.go b/stream_conformance_test.go index ec59772..0a0e3da 100644 --- a/stream_conformance_test.go +++ b/stream_conformance_test.go @@ -76,20 +76,3 @@ func TestCqueryLinkGeometryScope(t *testing.T) { t.Errorf("geometry channel = %q, want a tgsequence/queries path", ch) } } - -// The window-aggregation result carries the bounds Requirement 2 mandates. -func TestWindowResultShape(t *testing.T) { - ev := Event{ - "windowStart": "2026-01-01T00:00:00Z", - "windowEnd": "2026-01-01T00:00:30Z", - "aggregation": "AVG", - "property": "speed", - "value": 6.2, - "count": 3, - } - for _, k := range []string{"windowStart", "windowEnd", "aggregation", "value", "count"} { - if _, ok := ev[k]; !ok { - t.Errorf("window aggregate result missing required field %q", k) - } - } -} diff --git a/stream_engine_meos.go b/stream_engine_meos.go index 69c76b0..36121b3 100644 --- a/stream_engine_meos.go +++ b/stream_engine_meos.go @@ -155,7 +155,7 @@ func (h *meosHandle) runAggregate(ctx context.Context, spec QuerySpec, source <- if spec.Window.Type == "TUMBLING" { ts := instantUnix(in, len(win)) // best-effort event time if len(win) > 0 && ts >= winEndUnix { - if !h.emitWindow(ctx, spec, win) { + if !h.emitWindow(ctx, spec, win, unixRFC3339(winEndUnix-tumblingSpan), unixRFC3339(winEndUnix)) { return } win = win[:0] @@ -167,7 +167,7 @@ func (h *meosHandle) runAggregate(ctx context.Context, spec QuerySpec, source <- } else { // COUNT win = append(win, in) if len(win) >= spec.Window.Size { - if !h.emitWindow(ctx, spec, win) { + if !h.emitWindow(ctx, spec, win, win[0].T, win[len(win)-1].T) { return } win = win[:0] @@ -215,7 +215,7 @@ func (h *meosHandle) runHopping(ctx context.Context, spec QuerySpec, source <-ch } } if len(win) > 0 { - if !h.emitWindow(ctx, spec, win) { + if !h.emitWindow(ctx, spec, win, unixRFC3339(lo), unixRFC3339(nextEmit)) { return } } @@ -232,6 +232,9 @@ func (h *meosHandle) runHopping(ctx context.Context, spec QuerySpec, source <-ch } } +// unixRFC3339 writes a window bound, in Unix seconds, as an RFC 3339 UTC time. +func unixRFC3339(sec int64) string { return time.Unix(sec, 0).UTC().Format(time.RFC3339) } + // hopSeconds converts a HOPPING window hop+unit into seconds. func hopSeconds(w Window) int64 { hop := int64(w.Hop) @@ -247,16 +250,19 @@ func hopSeconds(w Window) int64 { return hop } -// emitWindow computes the aggregate over a closed window and emits it. -func (h *meosHandle) emitWindow(ctx context.Context, spec QuerySpec, win []Instant) bool { +// emitWindow computes the aggregate over a closed window and emits it, with the +// bounds of the window: [start, end) for a time window (TUMBLING, HOPPING), the +// span boundaries the window covers, and [start, end] for a COUNT window, the +// times of its first and last record. +func (h *meosHandle) emitWindow(ctx context.Context, spec QuerySpec, win []Instant, start, end string) bool { val, count, err := windowAggregate(spec.Ptype, spec.Agg, win) if err != nil { h.setStatus("failed") return false } ev := Event{ - "windowStart": win[0].T, - "windowEnd": win[len(win)-1].T, + "windowStart": start, + "windowEnd": end, "property": spec.Pname, "aggregation": spec.Agg, "value": val, diff --git a/stream_meos_test.go b/stream_meos_test.go index 224acfc..215cfe0 100644 --- a/stream_meos_test.go +++ b/stream_meos_test.go @@ -224,3 +224,86 @@ func TestMeosConcurrentQueries(t *testing.T) { t.Errorf("concurrent results sum = %v, want %v", sum, want) } } + +// windowResults submits an aggregation over the given window, feeds it one record +// per (second, value) pair from 2026-01-01T00:00:00Z, and answers the first n +// window results. +func windowResults(t *testing.T, w Window, recs [][2]float64, n int) []Event { + t.Helper() + e, _ := defaultStreamEngine() + ctx, cancel := context.WithCancel(context.Background()) + t.Cleanup(cancel) + src := make(chan Instant, len(recs)) + h, err := e.Submit(ctx, QuerySpec{Agg: "AVG", Window: w}, src) + if err != nil { + t.Fatal(err) + } + for _, r := range recs { + src <- Instant{T: fmt.Sprintf("2026-01-01T00:00:%02dZ", int(r[0])), V: r[1]} + } + var out []Event + for len(out) < n { + select { + case ev := <-h.Results(): + out = append(out, ev) + case <-time.After(5 * time.Second): + t.Fatalf("only %d of %d window results", len(out), n) + } + } + return out +} + +// Requirement 2: a window result carries the bounds of its window. A time window +// is [start, end), the span it covers whatever records fall in it; a COUNT window +// is [start, end], the times of its first and last record. +func TestMeosWindowBounds(t *testing.T) { + for _, c := range []struct { + what string + w Window + recs [][2]float64 + start, end string + }{ + // Records at 1 s and 2 s of the tumbling window [0 s, 3 s), closed by the record at 4 s. + {"TUMBLING", Window{Type: "TUMBLING", Size: 3, Unit: "SECONDS"}, + [][2]float64{{1, 10}, {2, 20}, {4, 40}}, "2026-01-01T00:00:00Z", "2026-01-01T00:00:03Z"}, + // The first hop boundary after a record at 0 s is 1 s: the window [-2 s, 1 s). + {"HOPPING", Window{Type: "HOPPING", Size: 3, Unit: "SECONDS", Hop: 1, HopUnit: "SECONDS"}, + [][2]float64{{0, 10}, {1, 20}}, "2025-12-31T23:59:58Z", "2026-01-01T00:00:01Z"}, + {"COUNT", Window{Type: "COUNT", Size: 2}, + [][2]float64{{1, 10}, {5, 20}}, "2026-01-01T00:00:01Z", "2026-01-01T00:00:05Z"}, + } { + t.Run(c.what, func(t *testing.T) { + ev := windowResults(t, c.w, c.recs, 1)[0] + if ev["windowStart"] != c.start || ev["windowEnd"] != c.end { + t.Errorf("window = [%v, %v], want [%s, %s]", ev["windowStart"], ev["windowEnd"], c.start, c.end) + } + }) + } +} + +// Requirement 3: a TUMBLING window is fixed-duration and non-overlapping, so +// each record falls in exactly one window and consecutive windows meet. +func TestMeosTumblingWindow(t *testing.T) { + // Windows of 2 s over records at 0..5 s: [0,2) {10,20}, [2,4) {30,40}, closed + // by the records at 2 s and 4 s. + evs := windowResults(t, Window{Type: "TUMBLING", Size: 2, Unit: "SECONDS"}, + [][2]float64{{0, 10}, {1, 20}, {2, 30}, {3, 40}, {4, 50}}, 2) + for i, want := range []struct { + start, end string + avg float64 + }{ + {"2026-01-01T00:00:00Z", "2026-01-01T00:00:02Z", 15}, + {"2026-01-01T00:00:02Z", "2026-01-01T00:00:04Z", 35}, + } { + ev := evs[i] + if ev["windowStart"] != want.start || ev["windowEnd"] != want.end { + t.Errorf("window %d = [%v, %v], want [%s, %s]", i, ev["windowStart"], ev["windowEnd"], want.start, want.end) + } + if ev["count"].(int) != 2 || math.Abs(ev["value"].(float64)-want.avg) > 1e-9 { + t.Errorf("window %d = AVG %v over %v records, want %v over 2", i, ev["value"], ev["count"], want.avg) + } + } + if evs[0]["windowEnd"] != evs[1]["windowStart"] { + t.Errorf("consecutive tumbling windows do not meet: %v then %v", evs[0]["windowEnd"], evs[1]["windowStart"]) + } +}