Skip to content

Commit

Permalink
docs: Update empty-tiles.md with maplibregl support for empty tile co…
Browse files Browse the repository at this point in the history
…ntent (#3396)

Since Maplibre GL v4.0.0 an empty response with 200 or 204 will be
treated as a transparent tile

### Motivation

update to documentation reflecting current support by maplibregl

### Modifications

update to documentation

### Verification

I tested this locally with 

```bash
nc -c 'echo -ne "HTTP/1.0 204 No Content\r\nAccess-Control-Allow-Origin: *\r\n\r\n";' -l -p 8080 -k

# and

nc -c 'echo -ne "HTTP/1.0 200 OK\r\nContent-Length: 0\r\nAccess-Control-Allow-Origin: *\r\n\r\n";' -l -p 8080 -k
```

with the following

```js
    const map = new maplibregl.Map({
        container: 'map',                                                                                                                                                                                                                      
        style: {
            'version': 8,
            'sources': {
                'osm': {
                    'type': 'raster',
                    'tiles': [ 'https://tile.openstreetmap.org/{z}/{x}/{y}.png' ],
                    'tileSize': 256
                },
                '204': {
                    'type': 'raster',
                    'tiles': [ 'http://localhost:8080/{z}/{x}/{y}' ],
                    'tileSize': 256
                }
            },
            'layers': [
                // bottom, drawn first
                {
                    'id': 'osm',
                    'type': 'raster',
                    'source': 'osm',
                    'minzoom': 0,
                    'maxzoom': 22
                },
                {
                    'id': '204',
                    'type': 'raster',
                    'source': '204',
                    'minzoom': 0,
                    'maxzoom': 22
                }
                // top, drawn last
            ]
        },
        center: [0, 0],
        zoom: 1
    });
```

no errors reported in the console and tiles from the 204 layer are drawn
transparently.

I also reviewed the maplibre-gl-js source code, there are two code paths
for loading tiles depending on how much the cache should be respected
and both code paths seem to support a 200/204 response with no content.

Co-authored-by: Blayne Chard <bchard@linz.govt.nz>
  • Loading branch information
andrewharvey and blacha authored Feb 20, 2025
1 parent 724d580 commit 3fa953c
Showing 1 changed file with 3 additions and 4 deletions.
7 changes: 3 additions & 4 deletions docs/operator-guide/empty-tiles.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,12 +46,13 @@ Pros:

- ✔️ Supported in ArcGIS Pro and QGIS
- ✔️ Supported by ArcGIS Online, Leaflet, and OpenLayers
- ✔️ Supported by maplibre [since v4.0.0](https://github.com/maplibre/maplibre-gl-js/blob/main/CHANGELOG.md#-bug-fixes-29)
- ✔️ Supported by [HTTP RFC](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok), which allows 0 byte `200 Ok` responses as long as the message framing indicates this (via `Content-length=0` response header
- ✔️ Recommended option from OGC Tile API

Cons:

- ❌ Not supported by maplibre/mapbox
- ❌ Not supported by mapbox gl
-[HTTP RFC](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) suggests that while valid, servers "ought to return 204 No content"

## 204 No Content
Expand All @@ -62,15 +63,13 @@ Pros:

- ✔️ Supported in ArcGIS Pro and QGIS
- ✔️ Supported by Leaflet and OpenLayers
- ✔️ Supported by maplibre [since v4.0.0](https://github.com/maplibre/maplibre-gl-js/blob/main/CHANGELOG.md#-bug-fixes-29)
- ✔️ Supported by [HTTP RFC](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok): "server ought to return 204 No content"
- ✔️ Recommended option from OGC Tile API

Cons:

- ❌ Not supported by ArcGIS Online
- ❌ Not supported by maplibre
- https://github.com/maplibre/maplibre-gl-js/pull/2325
- https://github.com/maplibre/maplibre-gl-js/pull/1586
- ❌ Not supported by mapbox gl
- https://github.com/mapbox/mapbox-gl-js/issues/9304
- Not always cached by browser
Expand Down

0 comments on commit 3fa953c

Please sign in to comment.