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"]) + } +}