TileJSON 3.0 support with layer fields discovery and cached /capabilities responses

[Rub21]

Update TileJSON version to 3.0.0 and adds the required fields property to VectorLayer.
​

• Implements a LayerFielder interface and a PostGIS-backed LayerFields method to infer attribute types per layer.
  ​
• Extends the /capabilities handler to populate fields from providers and cache TileJSON responses in memory

cc. @1ec5

[iwpnd]

Hey. This is an update that is well overdue. The implementation is alright. The LayerFielder makes sense. Yet incrementing the version to 3.0.0 is an increment to all providers alike even though they do not (yet) implement the LayerFielder. This in turn makes a capabilities.json from any other provider but the postgis provider an invalid TileJSON v3.
The handle_map_capabilities.go should therefor determine whether the provider implements the LayerFielder and if it doesn't yet, it should respond with a valid TileJSON v2.
This PR lacks some tests. Take a look into the postgis_test.go and snoop around in the testdata we setup locally. It should be straight forward to write a small test that covers the creation of the TileJSON v2 and v3 in handle_map_capabilities_test.go.

All in all, good work. Some nits, some questions, some potential redundancy and the question how to handle providers that do not yet impl a LayerFielder.

[ARolek]

I agree with @iwpnd, this is long over due so thanks for tackling it! I left a few comments inline and generally agree with the first pass review that @iwpnd gave.

[Rub21]

@iwpnd @ARolek

Thanks for taking the time to review this PR and for the helpful suggestions.
I’ve updated the implementation according to your feedback, including adding tests in server/handle_map_capabilities_test.go.
I’ve also deployed this branch to my Tegola server and the /capabilities and TileJSON 3.0 responses are working as expected in my setup.

https://vtiles.staging.openhistoricalmap.org/capabilities
https://vtiles.staging.openhistoricalmap.org/capabilities/ohm.json

[iwpnd]

@Rub21 thank you! i still think that the rwmutex will become a bottleneck in high concurrency environments and I have an idea how to address this. if you're in a rush you can keep your fork deployed, as I will not touch on functionality. i will however need some time to work on this and am unsure when I can get to it - this weekend maybe.

[Rub21]

I have an idea how to address this.

That would be great, Thank you!!

[ARolek]

@Rub21 thanks for tackling the code review comments. I'm traveling and wont get a chance to look at this until next week. Does look like govulncheck is failing too. Looks like we need to update go to 1.25.6. I will get this done.

[iwpnd]

@Rub21 can you please verify that you enabled us to commit to your branch? See here.

I simplified the caching from a dual-map + RWMutex setup to just sync.Map, where each entry holds both the sync.Once and TileJSON together. In this scnario sync.Map handles our read-heavy workload better under high concurrency since RWMutex performance drops significantly with load. Also fixed a bug where cancelled requests could cache incomplete data by switching to context.Background() for layer field fetching instead. That way even when cancelled, we ensure completetion for the next requester.

The main fix was versioning logic however, and looking into this in more detail I want to propose a different approach here.

We were using TileJSON 3.0.0 if any provider supported field metadata. However if you mix providers, this is causing inconsistent field availability across layers.
Now we only claim 3.0.0 when all providers support it, giving clients predictable behavior. I always initialize Fields as an empty map for spec compliance and renamed tilejson.Version to tilejson.Version3 for clarity.

Then I added error handling so failed builds don't get cached permanently - if buildTileJSON errors, we remove the cache entry so the next request can retry.
buildTileJSON is just the build logic put into its own method to declutter the ServeHTTP method a little.

When I was working through the TileJSON creation itself I was struggling to read the logic, tbh. I added a helper to find layers by ID - and removed that nested loop with the skip flag, and replaced the Atlas field with a GetMap function for cleaner dependency injection and easier testing where when GetMap is nil, we default to the defaultAtlas. Those test cases really made me think man.. the defaultAtlas is not a good idea in retrospect.

I have my changes tucked away in a separate commit, that I could contribute here if you give me the permission.

[iwpnd]

@Rub21 bumping this once more to your attention.

[Rub21]

@iwpnd Sorry for the delay. I was a bit stuck on a security issue with the project, but I've gotten back on track this week. I've just sent you an invitation to the repo, so you can commit to my branch. Since the PR was submitted from an organization account, works different i think , you should already have access to the repo and be able to commit. https://github.com/OpenHistoricalMap/tegola, thanks!

[iwpnd]

@Rub21 @ARolek I added my changes, see previous comment.

[ARolek]

@iwpnd

@Rub21 @ARolek I added my changes, see #1071 (comment).

Nice! Sorry I'm running a bit behind on reviews. Will get to it as soon as I can. Thanks for pushing for this one as it will be a great addition!

[gdey]

Overall this looks great to me.

I would like to have a discussion on the way map capabilities determines the TileJSON version. I like what we have, but think there should be a simple way for one to upgrade from 2.0 to 3.0, by setting the option and having Tegola let's us know which Layers need to what fields to be implemented.

[gdey]

I like this, but I think it would be good to have an option that tells us we want 3.0 TileJSON; if that options is set, we should error out pointing out the layers that don't support the LayerFielder; or maybe have another way. But, I do like the this as a fall back, and should be the default behavior.

[iwpnd]

Do you imagine this to provide a warning, but still start tegola with v3 or do you want tegola to err on startup when there's layers that do not yet support v3?

[gdey]

I think if the option is set that we want 3.0 TileJSON, then it should err on startup; and point out which layers don't support the LayerFielder. If the option is not set then it should use the fallback methods that's in this PR. What do you think?

[iwpnd]

Ok, sounds good to me.

[iwpnd]

Addressed in ff80e14 @gdey

[gdey]

LGTM

[iwpnd]

@ARolek let's gooo!