tileserver-gl 5.7.0-pre.0 → 5.7.0-pre.1

package/CHANGELOG.md

@@ -7,14 +7,22 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
-## 5.7.0-pre.0
+## 5.7.0-pre.1
 ### ✨ Features and improvements
 - feat: add opt-in Prometheus metrics endpoint ([#2211](https://github.com/maptiler/tileserver-gl/pull/2211)) (by [navidnabavi](https://github.com/navidnabavi))
+- feat: allow the data decorator to be asynchronous ([#2352](https://github.com/maptiler/tileserver-gl/pull/2352)) (by [acalcutt](https://github.com/acalcutt))
 
 ### 🐞 Bug fixes
 - fix: TypeError when style source value is a string (e.g. sprite path) ([#2179](https://github.com/maptiler/tileserver-gl/pull/2179)) (by [app/copilot-swe-agent](https://github.com/app/copilot-swe-agent))
 - fix: clean stale tile-source state on SIGHUP reload ([#2158](https://github.com/maptiler/tileserver-gl/pull/2158)) (by [bvitlas](https://github.com/bvitlas))
 - fix: correctly handle public_url in wmts endpoint ([#2205](https://github.com/maptiler/tileserver-gl/pull/2205)) (by [andrewlaguna824](https://github.com/andrewlaguna824))
+- fix: never leave a renderer request or pool slot unsettled ([#2347](https://github.com/maptiler/tileserver-gl/pull/2347)) (by [acalcutt](https://github.com/acalcutt))
+- fix: honour sparse set in archive metadata ([#2350](https://github.com/maptiler/tileserver-gl/pull/2350)) (by [acalcutt](https://github.com/acalcutt))
+- fix: data decorator never ran on Windows, or on PMTiles style sources ([#2351](https://github.com/maptiler/tileserver-gl/pull/2351)) (by [acalcutt](https://github.com/acalcutt))
+- chore: drop unused host-validation imports from server.js ([#2349](https://github.com/maptiler/tileserver-gl/pull/2349)) (by [acalcutt](https://github.com/acalcutt))
+- fix: restore the format-based sparse default ([#2348](https://github.com/maptiler/tileserver-gl/pull/2348)) (by [acalcutt](https://github.com/acalcutt))
+- fix: align 512px static map overlays ([#2344](https://github.com/maptiler/tileserver-gl/pull/2344)) (by [miakh](https://github.com/miakh))
+- fix: allow native install scripts under npm 12 so canvas builds ([#2343](https://github.com/maptiler/tileserver-gl/pull/2343)) (by [mikey923](https://github.com/mikey923))
 
 ## 5.6.0
 ### ✨ Features and improvements

package/docs/config.rst

@@ -214,6 +214,41 @@ Allows the rendering of inline marker icons or base64 urls.
 For security reasons only allow this if you can control the origins from where the markers are fetched!
 Not used by default.
 
+``dataDecorator``
+-----------------
+
+Path (relative to ``root``) to a JavaScript module whose default export is called to modify tile data and TileJSON on the fly. Not used by default.
+
+The module must be an ES module with a default export. The function is called as ``decorate(id, type, data, z, x, y)`` and **must return the value**, modified or not - returning nothing discards the data.
+
+The function may be ``async``, or return a promise. The return value is awaited, so the decorator can do asynchronous work such as a lookup or a fetch. It is awaited on every call, including once per tile for ``'data'``, so keep it fast or cache inside the module.
+
+``id``
+  The data source id from the config, or the source name from the style.
+
+``type``
+  Either ``'tilejson'`` or ``'data'``.
+
+``data``
+  For ``'tilejson'``, the TileJSON object served at ``/data/{id}.json``, or a style's local source object. For ``'data'``, a ``Buffer`` of vector tile bytes, already un-gzipped.
+
+``z``, ``x``, ``y``
+  Tile coordinates. Only passed for ``'data'``.
+
+``'data'`` is called for vector (pbf) sources only, both for ``/data/{id}/{z}/{x}/{y}.pbf`` and for the tiles fed to the raster renderer. Raster tiles are never passed through it.
+
+.. code-block:: js
+
+  // decorator.js
+  export default function (id, type, data, z, x, y) {
+    if (type === 'tilejson') {
+      data.attribution = 'Example attribution';
+    }
+    return data;
+  }
+
+Errors loading the module are logged and the server starts without a decorator, so check the startup output if it does not appear to run.
+
 
 ``styles``
 ==========
@@ -294,8 +329,14 @@ Here are the available options for each data source:
     * ``true`` - Returns HTTP 404, allowing clients like MapLibre to overzoom and use parent tiles. Use this for terrain or datasets with uneven zoom coverage.
     * ``false`` - Returns HTTP 204 (No Content), signaling an intentionally empty tile and preventing overzoom.
 
-    This can be set globally in the top-level options or per-data-source (per-source overrides global).
-    Default: Depends on tile format - ``false`` for vector tiles (pbf), ``true`` for raster tiles (png, webp, jpg, etc.).
+    Resolved from the first of these that is set, highest priority first:
+
+    1. ``sparse`` on the data source in this config file
+    2. ``sparse`` in the top-level ``options``
+    3. ``sparse`` in the archive's own metadata (the MBTiles ``metadata`` table, or the PMTiles metadata JSON)
+    4. The tile format - ``false`` for vector tiles (pbf), ``true`` for raster tiles (png, webp, jpg, etc.)
+
+    Config outranks archive metadata, so a source that declares the wrong value for your deployment can be corrected without rewriting the file. MBTiles metadata values are text; ``"true"``/``"false"`` and ``"1"``/``"0"`` are both understood, and anything else is ignored rather than guessed at.
 
 ``s3Profile`` (string)
     Specifies the AWS credential profile to use for S3 PMTiles sources. The profile must be defined in your ``~/.aws/credentials`` file.

package/docs/usage.rst

@@ -119,7 +119,8 @@ TileServer GL can fetch tiles from remote HTTP/HTTPS sources referenced in your
 
 **Default behavior:**
 - Default timeout is 15 seconds (15000 milliseconds)
-- If a remote tile request exceeds this timeout, an error is logged and an empty tile is returned to the renderer
+- If a remote tile request exceeds this timeout, an error is logged and the tile is treated as missing
+- What "missing" means follows the source's ``sparse`` setting: raster sources are sparse by default, so MapLibre overzooms from a parent tile, while vector sources are not, so an empty tile is returned to the renderer. See ``sparse`` in :doc:`/config`.
 
 **Tuning the timeout:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tileserver-gl",
-  "version": "5.7.0-pre.0",
+  "version": "5.7.0-pre.1",
   "description": "Map tile server for JSON GL styles - vector and server side generated raster tiles",
   "main": "src/main.js",
   "bin": {
@@ -37,8 +37,8 @@
     "docker": "docker build . && docker run --rm -i -p 8080:8080 $(docker build -q .)"
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.1055.0",
-    "@jsse/pbfont": "^0.3.3",
+    "@aws-sdk/client-s3": "^3.1081.0",
+    "@jsse/pbfont": "^0.3.4",
     "@mapbox/mapbox-gl-rtl-text": "0.4.0",
     "@mapbox/mbtiles": "0.12.1",
     "@mapbox/polyline": "^1.2.1",
@@ -46,14 +46,14 @@
     "@mapbox/vector-tile": "3.0.0",
     "@maplibre/maplibre-gl-inspect": "1.8.2",
     "@maplibre/maplibre-gl-native": "6.4.1",
-    "@maplibre/maplibre-gl-style-spec": "24.8.5",
+    "@maplibre/maplibre-gl-style-spec": "24.10.0",
     "@sindresorhus/fnv1a": "3.1.0",
     "advanced-pool": "0.3.3",
     "canvas": "3.2.3",
     "chokidar": "5.0.0",
     "clone": "2.1.2",
     "color": "5.0.3",
-    "commander": "14.0.3",
+    "commander": "15.0.0",
     "copyfiles": "2.4.1",
     "cors": "2.8.6",
     "express": "5.2.1",
@@ -62,36 +62,36 @@
     "leaflet": "1.9.4",
     "leaflet-hash": "0.2.1",
     "maplibre-gl": "5.24.0",
-    "morgan": "1.10.1",
-    "pbf": "5.0.0",
+    "morgan": "1.11.0",
+    "pbf": "5.1.0",
     "pmtiles": "4.4.1",
-    "proj4": "2.20.8",
+    "proj4": "2.20.9",
     "prom-client": "^15.1.3",
     "sanitize-filename": "1.6.4",
     "secure-json-parse": "^4.1.0",
-    "semver": "^7.8.1",
-    "sharp": "0.34.5",
+    "semver": "^7.8.5",
+    "sharp": "0.35.3",
     "tileserver-gl-styles": "2.0.0"
   },
   "devDependencies": {
-    "@commitlint/cli": "^21.0.1",
-    "@commitlint/config-conventional": "^21.0.1",
+    "@commitlint/cli": "^21.2.0",
+    "@commitlint/config-conventional": "^21.2.0",
     "@eslint/js": "^10.0.1",
-    "@typescript-eslint/eslint-plugin": "^8.60.0",
-    "@typescript-eslint/parser": "^8.60.0",
+    "@typescript-eslint/eslint-plugin": "^8.63.0",
+    "@typescript-eslint/parser": "^8.61.1",
     "chai": "6.2.2",
     "cross-env": "^10.1.0",
-    "eslint": "^10.4.0",
+    "eslint": "^10.6.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-jsdoc": "^63.0.0",
-    "eslint-plugin-prettier": "^5.5.5",
-    "eslint-plugin-security": "^4.0.0",
-    "globals": "^17.6.0",
-    "lint-staged": "^17.0.5",
+    "eslint-plugin-jsdoc": "^63.0.12",
+    "eslint-plugin-prettier": "^5.5.6",
+    "eslint-plugin-security": "^4.0.1",
+    "globals": "^17.7.0",
+    "lint-staged": "^17.0.8",
     "mocha": "^11.7.6",
     "node-addon-api": "^8",
     "pixelmatch": "^7.2.0",
-    "prettier": "^3.8.3",
+    "prettier": "^3.9.4",
     "should": "^13.2.3",
     "supertest": "^7.2.2",
     "yaml-lint": "^1.7.0"
@@ -113,5 +113,10 @@
   "bugs": {
     "url": "https://github.com/maptiler/tileserver-gl/issues"
   },
-  "homepage": "https://github.com/maptiler/tileserver-gl#readme"
+  "homepage": "https://github.com/maptiler/tileserver-gl#readme",
+  "allowScripts": {
+    "canvas": true,
+    "sqlite3": true,
+    "@maplibre/maplibre-gl-native": true
+  }
 }

package/src/main.js

@@ -2,6 +2,7 @@
 
 'use strict';
 import os from 'os';
+import { inspect } from 'node:util';
 
 const envSize = parseInt(process.env.UV_THREADPOOL_SIZE, 10);
 process.env.UV_THREADPOOL_SIZE = Math.ceil(
@@ -25,18 +26,63 @@ import { openMbTilesWrapper } from './mbtiles_wrapper.js';
 // Global Error Handlers - Prevent server crashes from unhandled errors
 // ============================================================================
 
+// Keeping the process alive hides the failure unless the log says what broke,
+// so report the stack, any cause chain, and how often this has happened. A
+// repeating count is the signal that something is looping, not misfiring once.
+const survivedErrorCounts = new Map();
+const SURVIVED_ERROR_KEYS_MAX = 500;
+
+/**
+ * Renders a thrown value as text, following up to `depth` levels of `cause`.
+ * @param {unknown} err - The thrown value or rejection reason.
+ * @param {number} [depth] - Remaining cause levels to follow.
+ * @returns {string} A printable description of the error.
+ */
+function describeError(err, depth = 3) {
+  if (!(err instanceof Error)) {
+    return `Non-Error value: ${inspect(err, { depth: 3 })}`;
+  }
+  let text = err.stack || `${err.name}: ${err.message}`;
+  if (err.cause !== undefined && depth > 0) {
+    text += `\nCaused by: ${describeError(err.cause, depth - 1)}`;
+  }
+  return text;
+}
+
+/**
+ * Reports an error the process deliberately survived.
+ * @param {string} kind - The handler that fired.
+ * @param {unknown} err - The thrown value or rejection reason.
+ * @returns {void}
+ */
+function reportSurvivedError(kind, err) {
+  const detail = describeError(err);
+  const key = `${kind} :: ${err instanceof Error ? err.message : detail}`;
+
+  let occurrence = '';
+  if (survivedErrorCounts.has(key)) {
+    const count = survivedErrorCounts.get(key) + 1;
+    survivedErrorCounts.set(key, count);
+    occurrence = ` (occurrence ${count})`;
+  } else if (survivedErrorCounts.size < SURVIVED_ERROR_KEYS_MAX) {
+    // Bounded: distinct messages can carry tile coordinates or URLs, and an
+    // unbounded tally of them would be a leak of its own.
+    survivedErrorCounts.set(key, 1);
+    occurrence = ' (occurrence 1)';
+  }
+
+  console.error(`[${kind}] server continuing after error${occurrence}:`);
+  console.error(detail);
+}
+
 // Prevent unhandled promise rejections from crashing the server
-process.on('unhandledRejection', (reason, promise) => {
-  console.error('Unhandled Promise Rejection at:', promise);
-  console.error('Reason:', reason);
-  // Don't exit - keep server running
+process.on('unhandledRejection', (reason) => {
+  reportSurvivedError('unhandledRejection', reason);
 });
 
 // Prevent uncaught exceptions from crashing the server
 process.on('uncaughtException', (error) => {
-  console.error('Uncaught Exception:', error);
-  console.error('Stack:', error.stack);
-  // Don't exit - keep server running
+  reportSurvivedError('uncaughtException', error);
 });
 
 // ============================================================================

package/src/render_mode.js

@@ -0,0 +1,20 @@
+'use strict';
+
+/**
+ * Converts a TileServer zoom level to the zoom expected by MapLibre Native.
+ * @param {number} zoom TileServer zoom level.
+ * @param {number} logicalWidth Unscaled request width in pixels.
+ * @param {'tile'|'static'} mode Rendering mode.
+ * @returns {number} MapLibre Native zoom level.
+ */
+export function getMapLibreRenderZoom(zoom, logicalWidth, mode) {
+  if (mode === 'static') {
+    return Math.max(0, zoom - 1);
+  }
+
+  if (mode === 'tile') {
+    return Math.max(0, logicalWidth === 512 ? zoom : zoom - 1);
+  }
+
+  throw new Error(`Unsupported render mode: ${mode}`);
+}

package/src/serve_data.js

@@ -15,6 +15,8 @@ import {
   isValidRemoteUrl,
   fetchTileData,
   lonLatToTilePixel,
+  parseOptionalBoolean,
+  resolveSparse,
 } from './utils.js';
 import { getPMtilesInfo, openPMtiles } from './pmtiles_adapter.js';
 import { gunzipP, gzipP } from './promises.js';
@@ -139,7 +141,7 @@ export const serve_data = {
 
       if (tileJSONFormat === 'pbf') {
         if (options.dataDecoratorFunc) {
-          data = options.dataDecoratorFunc(
+          data = await options.dataDecoratorFunc(
             req.params.id,
             'data',
             data,
@@ -619,19 +621,29 @@ export const serve_data = {
     delete tileJSON['scheme'];
     tileJSON['tilejson'] = '3.0.0';
 
+    // MBTiles metadata is a table of strings, so a `sparse` row arrives as
+    // "false" - truthy at face value. Take it as a boolean here and drop the
+    // raw key, so nothing downstream (the data decorator, the served TileJSON)
+    // ever sees the unparsed form. The resolved value is put back below.
+    const metadataSparse = parseOptionalBoolean(tileJSON.sparse);
+    delete tileJSON['sparse'];
+
     Object.assign(tileJSON, params.tilejson || {});
     fixTileJSONCenter(tileJSON);
 
     if (options.dataDecoratorFunc) {
-      tileJSON = options.dataDecoratorFunc(id, 'tilejson', tileJSON);
+      tileJSON = await options.dataDecoratorFunc(id, 'tilejson', tileJSON);
     }
 
-    // Determine sparse: per-source overrides global, then format-based default
-    // sparse=true -> 404 (allows overzoom)
-    // sparse=false -> 204 (empty tile, no overzoom)
-    // Default: vector tiles (pbf) -> false, raster tiles -> true
-    const isVector = tileJSON.format === 'pbf';
-    const sparse = params.sparse ?? options.sparse ?? !isVector;
+    // sparse=true -> 404 (allows overzoom), sparse=false -> 204 (empty tile)
+    const sparse = resolveSparse({
+      perSource: params.sparse,
+      globalOption: options.sparse,
+      metadata: metadataSparse,
+      isVector: tileJSON.format === 'pbf',
+    });
+    // Advertise what the server will actually do, not what the archive claimed.
+    tileJSON.sparse = sparse;
 
     // eslint-disable-next-line security/detect-object-injection -- id is from config file data source names
     repo[id] = {