mapsrv/importer tile tool: R121 decoded-tile check + standardized benchmarks + size validation

art commented

2026-08-16 01:17:27 +00:00

Owner

Part of the #115 plan and the #125 remainder: R121's decoded-tile half (docs/country-requirements.md R121: "Confirms stop_z, mvt_exclude and the attribute set at once") cannot be an importer acceptance test, because the check needs to parse the served MVT. MVT is protobuf; Postgres has no decoder and no protobuf extension, so a SQL test would have to reimplement the wire format in SQL — thousands of lines of varint parsing for a check that is meant to be cheap. #125 ships the stop_z half as the R30 floor/ceiling tests and scopes this half out with this reason.

Proposal: a Go test in mapsrv (or importer) that connects to the live DB, serves/decodes a tile per layer via the zxy_<layer> functions, and asserts the tile's keys equal the contract's mvt_exclude-adjusted attr_names. The pieces that exist: scripts/mvt-decode.py is the hand decoder (fields() walks the tile/layer/feature protobuf), and mapsrv's glyph test already decodes protobuf in Go (mapsrv/glyph_check_test.go decodeGlyph) — so the decoder pattern is established on both sides. Where it should live and how it gets run (a make target? part of mapsrv tests?) is the open question; the acceptance-test mechanism deliberately covers only SQL against the database, so this is a new, separate mechanism rather than an extension of it.

What the check would assert per shared layer: the tile's layer keys = attr_names minus mvt_exclude plus the machinery columns (geom, country). A leak (part_key on cover, rank on places) or a dropped attribute goes red.

Scope expanded 2026-08-16 (maintainer): this issue is now the project's
tile-serving/decoding/measuring mechanism, absorbing from #127 its
standardized-benchmark and size-validation machinery. #127 keeps only the
optimization work and uses this tool to measure progress.

Standardized benchmarks (absorbed from #127)

Pick a few zoom levels and interesting points (capitals, whole countries,
etc.) and fetch 9x9 tiles around each zoom/point combination (9x9 is
roughly one screen), and time it. No HTTP needed — serving from the database
(zxy_ functions) is sufficient. Report in a parseable way (JSON or
equivalent) so results can be saved and graphed, ideally including per-tile
byte sizes. Open questions now resolved: it lives in the same mechanism as
the R121 check above (a Go tool against the live DB, run via a make target /
test); the database is often ahead of main, so benchmark results describe the
live DB — CI correlation is a nice-to-have, not a requirement.

Size validation (absorbed from #127)

The tool must also produce per-layer/per-zoom tile-weight reports: heaviest
tiles per layer (bytes), so an optimization pass can find the offenders and
show before/after. This generalises the one-off z5 Stockholm 8 MB SQL check
into a real measurement tool; the SQL acceptance test stays where it is.

Part of the #115 plan and the #125 remainder: R121's *decoded-tile* half (docs/country-requirements.md R121: "Confirms stop_z, mvt_exclude and the attribute set at once") cannot be an importer acceptance test, because the check needs to parse the served MVT. MVT is protobuf; Postgres has no decoder and no protobuf extension, so a SQL test would have to reimplement the wire format in SQL — thousands of lines of varint parsing for a check that is meant to be cheap. #125 ships the `stop_z` half as the R30 floor/ceiling tests and scopes this half out with this reason. Proposal: a Go test in mapsrv (or importer) that connects to the live DB, serves/decodes a tile per layer via the `zxy_<layer>` functions, and asserts the tile's keys equal the contract's `mvt_exclude`-adjusted `attr_names`. The pieces that exist: `scripts/mvt-decode.py` is the hand decoder (fields() walks the tile/layer/feature protobuf), and mapsrv's glyph test already decodes protobuf in Go (mapsrv/glyph_check_test.go decodeGlyph) — so the decoder pattern is established on both sides. Where it should live and how it gets run (a `make` target? part of mapsrv tests?) is the open question; the acceptance-test mechanism deliberately covers only SQL against the database, so this is a new, separate mechanism rather than an extension of it. What the check would assert per shared layer: the tile's layer keys = `attr_names` minus `mvt_exclude` plus the machinery columns (geom, country). A leak (part_key on cover, rank on places) or a dropped attribute goes red. --- **Scope expanded 2026-08-16 (maintainer):** this issue is now the project's tile-serving/decoding/measuring *mechanism*, absorbing from #127 its standardized-benchmark and size-validation machinery. #127 keeps only the optimization work and uses this tool to measure progress. ## Standardized benchmarks (absorbed from #127) Pick a few zoom levels and interesting points (capitals, whole countries, etc.) and fetch **9x9 tiles** around each zoom/point combination (9x9 is roughly one screen), and time it. No HTTP needed — serving from the database (zxy_<layer> functions) is sufficient. Report in a **parseable** way (JSON or equivalent) so results can be saved and graphed, ideally including per-tile byte sizes. Open questions now resolved: it lives in the same mechanism as the R121 check above (a Go tool against the live DB, run via a make target / test); the database is often ahead of main, so benchmark results describe the live DB — CI correlation is a nice-to-have, not a requirement. ## Size validation (absorbed from #127) The tool must also produce per-layer/per-zoom tile-weight reports: heaviest tiles per layer (bytes), so an optimization pass can find the offenders and show before/after. This generalises the one-off z5 Stockholm 8 MB SQL check into a real measurement tool; the SQL acceptance test stays where it is.

art referenced this issue from a commit

2026-08-16 01:19:40 +00:00

#125: the rest of the global/MVT acceptance tests in conf/common.yaml

art referenced this issue

2026-08-16 01:19:42 +00:00

#125: the rest of the global/MVT acceptance tests in conf/common.yaml #140

art referenced this issue

2026-08-16 01:19:54 +00:00

Global/MVT acceptance tests: the rest of the config-level checks #125

art referenced this issue

2026-08-16 05:38:01 +00:00

R121's decoded-tile check needs a mapsrv-side MVT decoder (not a SQL acceptance test) #138

art referenced this issue

2026-08-16 05:52:33 +00:00

Tiles are probably too heavy right now — optimization passes, measured with #139's tile tool #127

art commented

2026-08-16 05:55:42 +00:00

Author

Owner

This is somewhat related tests from #127. We should have a shape that supports checking tile sizes and benchmarking of the load time for a large amount of tiles.

art referenced this issue

2026-08-16 06:07:34 +00:00

Tiles are probably too heavy right now — optimization passes, measured with #139's tile tool #127

art referenced this issue from a commit

2026-08-16 06:31:03 +00:00

#125: the rest of the global/MVT acceptance tests in conf/common.yaml

art-bot was assigned by art

2026-08-16 06:32:42 +00:00

art changed title from ~~R121's decoded-tile check needs a mapsrv-side MVT decoder (not a SQL acceptance test)~~ to mapsrv/importer tile tool: R121 decoded-tile check + standardized benchmarks + size validation

2026-08-16 06:41:38 +00:00

art added the

claude-wip

label

2026-08-16 06:41:49 +00:00

art referenced this issue from a commit

2026-08-16 07:06:42 +00:00

tile tool: R121 decoded-tile check, standardized benchmarks, size validation (#139)

art referenced this issue from a pull request that will close it,

2026-08-16 07:06:43 +00:00

tile tool: R121 decoded-tile check, standardized benchmarks, size validation (#139) #142

art referenced this issue from a commit