Martin's Accept header vs other maplibre client

[michaelkirk]

As of #2775, Martin supports converting MVT tiles to MLT (and vice versa) on the fly, which is cool in theory. But in practice, it's been challenging to actually use it with other clients. I'm going to start with just a statement of the problem I'm having for now, and maybe follow up with a proposed solution later.

As background, I'll be referring to 3 levels of requests:

1. style.json (e.g. /style/my-style )
2. tile.json (source metadata) - (e.g. /my-source)
3. individual tile (e.g. /my-source/{x}/{y}/{z})

MaplibreGL JS

You need to patch the js client to send the appropriate Accepts header while requesting tiles. Something like this:

   const mapOptions: MapOptions = {
     container: mapContainerId,
-    style: '/tileserver/styles/basic/style.json', // style URL
+    style: '/tileserver/style/basic-v2',
+    transformRequest: (url, resourceType) => {
+      if (resourceType === 'Tile' && url.includes('areamap')) {
+        return {
+          url,
+          headers: { Accept: 'application/vnd.maplibre-tile' },
+        };
+      }
+      return { url };
+    },
   };

That's sufficient to request MLT, but the JS client will still assume the response is MVT unless you also update the style.json to declare the encoding of the source as mlt.

Something like this:

GET /tileserver/style/basic-v2
...
{
    "sources": {
        "openmaptiles": {
            "url": "http://localhost:8080/tileserver/areamap-mlt",
            "encoding": "mlt",
            "type": "vector"
        },
    },

That works, but it's awkward because we've "hardcoded" something at the style level, when really getting MLT from martin requires headers be sent to the individual tile requests, and does not depend on the source encoding.

Maplibre Native iOS (maybe other native platforms too - but I'm only using iOS)

You similarly need to patch the client to set the accepts headers. Something like this...

func makeUIView(context: Context) -> Self.UIViewType {
...
+    assert(MLNNetworkConfiguration.sharedManager.delegate == nil)
+    MLNNetworkConfiguration.sharedManager.delegate = context.coordinator
...
}

+extension MapViewWrapper.Coordinator: MLNNetworkConfigurationDelegate {
+  func willSend(_ request: NSMutableURLRequest) -> NSMutableURLRequest {
+    if request.url?.path.contains("/tileserver/areamap-mlt") == true {
+      request.setValue("application/vnd.maplibre-tile", forHTTPHeaderField: "Accept")
+    }
+    return request
+  }
+}

But this isn't working. I think it's because maplibre native is expecting the encoding: mlt to be set for the source metadata (the tile.json) not the style. Currently I don't think it's possible to edit the tile.json in the way for martin. Plus it would, like the note above, be awkward to "hard code" the encoding for a tile.json when ultimately it's the request headers which dictate what kind of tile response you get.

[CommanderStorm]

Here is the issue where I give the rationale for this:

maplibre/maplibre-native#4236 (comment)

I have open PRs against gl-js and native that would unblock tile servers like martin being actually able to serve MLT without that pain.
So essentially, this needs signoff from @louwers

The content negotiation for adding MLT to tiles.json is also in the plan, but first we need the basics to work if the style has encoding: mlt set.
Until we get movement on the PR, I can't do anything.

Essentially:

1. First PR: if you set encoding: mlt in the style, you get MLT from the server.
2. Second PR:
   • if your client tells the server that the tilejson should include encoding: mlt field,
   • we will includes it and
   • the client will autoconfigures that this source is encoding: mlt
   • First PR means that now the server and client are in-sync.

Works with middleboxes, legacy clients, ...

[CommanderStorm]

naa.. just a header.
Which Key/Value I have not thought deeply about.

[michaelkirk]

At first I thought a header made sense, because it's like an Accept header, but for a subsequent request:

"Give me the JSON so that I can make a subsequent request for MLT"

I'm sure we can make a header work, but it presents some challenges. A couple that come to mind:

• We'll have to tell our CDN to vary on this bespoke header. That should be straight forward enough to add a Vary header.
• Our requests will no longer be "simple" in the CORS sense. I'm not sure how to get around that.

Can you speak to the benefits of using a custom header? Is there a use case you're optimizing for?

[CommanderStorm]

The main benefit is auto-upgrading, so as long as your rendering engine and data provider support the right "encoding", we can haggle out a better connection.

Our requests will no longer be "simple" in the CORS sense. I'm not sure how to get around that.

Good point..
Maybe we might need a new tilejson spec and register an Accept MIME type for it.
This way, it would still be simple, we don't want the CORS roundtrip.

There are a few issues in that spec (f.ex. the weird projection support) anyhow, so forking it would have benfits.

[michaelkirk]

I don't think registering the mime type would be sufficient because the header we'd use wouldn't be the Accept header.

When we are requesting tilejson, we Accept: json

It's that we want that json to include a field "encoding: mlt"

It would need to be some other header which specifies this, right?

[CommanderStorm]

When we are requesting tilejson, we Accept: json

No, that would be breaking.
I am suggesting

Accept: application/json, application/vnd.maplibre.tilesjson

If we know that application/vnd.maplibre.tilesjson is supported, we can send it back ^^

[michaelkirk]

I appreciate the elegance of the Accept header solution. However, if that's too big of a lift to coordinate across the ecosystem, adding a configurable "output format" in martin's sources config, rather than reflecting on the clients Accept header, might be an easier lift that gets things working.

[CommanderStorm]

It REALLY should not be a lift, sending headers should not be hard.
The PR is open, just needs to be merged.
If that is too large of a change, we have other problems.

If the PR gets rejected we can still add heuristics like .mlt -> MLT or something like that.
I would like to avoid temporary hacks because if we add them we are stuck with them, even if there now exists header autoconfig.

Can I get you unstuck by adding a reverse-proxy in front attaching the header?

[michaelkirk]

I'm already setting the headers, so no issue there (though it should be easier). The issue is that martin is not responding in a way that is usable by the native client.

I've set up this example here: https://michaelkirk.github.io/mlt_style_demo

I'm going to move this over to MLN since I suspect this might be a bug there. In any case the situation is a bit confused from my perspective. 😵

[CommanderStorm]

thanks and sorry for all this pain that you are experiencing 😶‍🌫️