Proposal: improvements to local MBTiles FileSource

[brendan-ward]

Context: I'm working on Python bindings to build a self-hosted static renderer similar to mbgl-renderer that I built on top of the (now unmaintained?) mapbox-gl-native NodeJS bindings and was starting to build up a similar FileSource for local mbtiles when I discovered it was already implemented here (thanks!).

I use a somewhat different approach to resolving local mbtiles files to tileJSON and tiles: e.g., "mbtiles://land/{z}/{x}/{y}.pbf" => /<mbtiles root path>/land.mbtiles tile request. (style JSON example)

though I am open to other alternatives of resolving this that don't require full filesystem paths in the style JSON files; an approach like is used for assets is more appropriate. Style JSON strings are sent by client applications to the static renderer; the root path containing the mbtiles files is set as a property for running the static renderer server.

It looks like the current implementation only resolves absolute file paths? I couldn't find a full request URL or test that would reveal this in the codebase, but from inspection of the code a tile request looks something like /<absolute mbtiles file path>?file={x}/{y}/{z}.pbf

Is there more documentation / examples for this FileSource anywhere?

I'd like to make the following changes to the MBTiles FileSource, but wanted to be sure that the overall direction seems reasonable:

• rename MaptilerFileSource => MBTilesFileSource
• move implementations of tileJSON construction and tile unzipping to separate utility files
• add property to ResourceOptions to set root path containing local MBTiles files, similar to asset path
• make resolving tileJSON / tile request URLs more configurable
• add tests for MBTilesFileSource and a couple small mbtiles files as test fixtures; I don't see that there are any tests now, so it's a bit hard to know if the above changes would break any downstream usage

[petr-pokorny-1]

Good ideas. Unfortunately we currently don't have any documentation for this FileSource, but you can check https://github.com/maplibre/maplibre-gl-native/issues/17

[wipfli]

This could be related to relative paths in the style spec. See https://github.com/maplibre/maplibre-gl-js/pull/645

[brendan-ward]

This could be related to relative paths in the style spec

At first glance, that seems like it would add unwanted complexity and potential confusion here because:

• the TileJSON of a given MBTiles file is programmatically generated here; we need a clear route to the underlying MBTiles file to generate that
• the style JSON may be passed in as a string or a URL; if a string it doesn't exist on the filesystem in order to refer to other things relative to it

Instead, my proposal here was more about passing in a property to ResourceOptions to define a root location that could then be used to resolve relative paths in the style JSON to absolute paths, similar to how the asset paths work.

At first, I thought the use of absolute paths was going to add a lot of friction compared to relative paths (e.g., in mbgl-renderer) but that has not proven to be the case. For my existing use cases, the caller (e.g., a Python wrapper) lives on the same server and has knowledge of the absolute paths. If we were to build a new service API that allowed the caller to pass in render requests and style JSON via HTTP requests, we could just add another bit of configuration there and have it do a find / replace on mbtiles:// paths to resolve relative paths in the style JSON to absolute paths on the server before calling in to maplibre-gl-native code. Meaning: it would be convenient for the caller, but not essential, for maplibre-gl-native to support resolving relative to absolute paths to MBTiles file sources.