tileserver-gl-light 5.6.1-pre.0 → 5.7.0-pre.0

package/CHANGELOG.md

@@ -7,9 +7,14 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
-## 5.6.1-pre.0
+## 5.7.0-pre.0
+### ✨ 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))
+
 ### 🐞 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))
 
 ## 5.6.0
 ### ✨ Features and improvements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tileserver-gl-light",
-  "version": "5.6.1-pre.0",
+  "version": "5.7.0-pre.0",
   "description": "Map tile server for JSON GL styles - serving vector tiles",
   "main": "src/main.js",
   "bin": {
@@ -37,13 +37,13 @@
     "docker": "docker build . && docker run --rm -i -p 8080:8080 $(docker build -q .)"
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.1045.0",
+    "@aws-sdk/client-s3": "^3.1055.0",
     "@jsse/pbfont": "^0.3.3",
     "@mapbox/mapbox-gl-rtl-text": "0.4.0",
     "@mapbox/mbtiles": "0.12.1",
     "@mapbox/polyline": "^1.2.1",
     "@mapbox/sphericalmercator": "2.0.2",
-    "@mapbox/vector-tile": "2.0.4",
+    "@mapbox/vector-tile": "3.0.0",
     "@maplibre/maplibre-gl-inspect": "1.8.2",
     "@maplibre/maplibre-gl-style-spec": "24.8.5",
     "@sindresorhus/fnv1a": "3.1.0",
@@ -61,12 +61,13 @@
     "leaflet-hash": "0.2.1",
     "maplibre-gl": "5.24.0",
     "morgan": "1.10.1",
-    "pbf": "4.0.1",
+    "pbf": "5.0.0",
     "pmtiles": "4.4.1",
     "proj4": "2.20.8",
+    "prom-client": "^15.1.3",
     "sanitize-filename": "1.6.4",
     "secure-json-parse": "^4.1.0",
-    "semver": "^7.8.0",
+    "semver": "^7.8.1",
     "tileserver-gl-styles": "2.0.0"
   },
   "keywords": [

package/src/main.js

@@ -113,6 +113,10 @@ program
     '--ignore-missing-files',
     'Continue startup even if configured mbtiles/pmtiles files are missing',
   )
+  .option(
+    '--metrics',
+    'Enable Prometheus metrics endpoint (env: TILESERVER_GL_METRICS)',
+  )
   .version(packageJson.version, '-v, --version');
 program.parse(process.argv);
 const opts = program.opts();
@@ -166,6 +170,11 @@ const startServer = (configPath, config) => {
     publicUrl,
     allowedHosts,
     ignoreMissingFiles: opts.ignoreMissingFiles,
+    metrics: opts.metrics || process.env.TILESERVER_GL_METRICS === 'true',
+    metricsPort: (() => {
+      const port = parseInt(process.env.METRICS_PORT, 10);
+      return !isNaN(port) && port > 0 ? port : 9090;
+    })(),
   });
 };
 

package/src/mbtiles_wrapper.js

@@ -8,6 +8,7 @@ class MBTilesWrapper {
   constructor(mbtiles) {
     this._mbtiles = mbtiles;
     this._getInfoP = util.promisify(mbtiles.getInfo.bind(mbtiles));
+    this._closeP = util.promisify(mbtiles.close.bind(mbtiles));
   }
 
   /**
@@ -25,6 +26,14 @@ class MBTilesWrapper {
   getInfo() {
     return this._getInfoP();
   }
+
+  /**
+   * Closes the underlying MBTiles database handle.
+   * @returns {Promise<void>} A promise that resolves when the database is closed.
+   */
+  close() {
+    return this._closeP();
+  }
 }
 
 /**

package/src/metrics.js

@@ -0,0 +1,70 @@
+// src/metrics.js
+import {
+  Registry,
+  Counter,
+  Histogram,
+  Gauge,
+  collectDefaultMetrics,
+} from 'prom-client';
+
+export const registry = new Registry();
+
+collectDefaultMetrics({ register: registry });
+
+export const httpRequestsTotal = new Counter({
+  name: 'tileserver_http_requests_total',
+  help: 'Total number of HTTP requests',
+  labelNames: ['method', 'route', 'status_code'],
+  registers: [registry],
+});
+
+export const httpRequestDuration = new Histogram({
+  name: 'tileserver_http_request_duration_seconds',
+  help: 'HTTP request duration in seconds',
+  labelNames: ['method', 'route', 'status_code'],
+  buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
+  registers: [registry],
+});
+
+export const tilesServedTotal = new Counter({
+  name: 'tileserver_tiles_served_total',
+  help: 'Total number of tiles served',
+  labelNames: ['type', 'name'],
+  registers: [registry],
+});
+
+export const tileRenderDuration = new Histogram({
+  name: 'tileserver_tile_render_duration_seconds',
+  help: 'Tile pipeline duration in seconds (includes pool wait + render + encode)',
+  labelNames: ['name', 'zoom'],
+  buckets: [0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
+  registers: [registry],
+});
+
+export const tileErrorsTotal = new Counter({
+  name: 'tileserver_tile_errors_total',
+  help: 'Total number of tile errors',
+  labelNames: ['type', 'name'],
+  registers: [registry],
+});
+
+export const renderPoolSize = new Gauge({
+  name: 'tileserver_render_pool_size',
+  help: 'Total objects in render pool',
+  labelNames: ['name'],
+  registers: [registry],
+});
+
+export const renderPoolActive = new Gauge({
+  name: 'tileserver_render_pool_active',
+  help: 'Active (borrowed) objects in render pool',
+  labelNames: ['name'],
+  registers: [registry],
+});
+
+export const renderPoolWaiting = new Gauge({
+  name: 'tileserver_render_pool_waiting',
+  help: 'Clients waiting for a render pool object',
+  labelNames: ['name'],
+  registers: [registry],
+});

package/src/pmtiles_adapter.js

@@ -292,6 +292,23 @@ class PMTilesFileSource {
     );
     return { data: ab };
   }
+
+  /**
+   * Closes the underlying file descriptor for local PMTiles sources.
+   * @returns {void}
+   */
+  close() {
+    if (typeof this.fd === 'number') {
+      const fd = this.fd;
+      try {
+        fs.closeSync(fd);
+      } catch (err) {
+        console.warn(`Failed to close PMTiles file descriptor ${fd}:`, err);
+      } finally {
+        this.fd = null;
+      }
+    }
+  }
 }
 
 /**
@@ -315,6 +332,22 @@ async function readFileBytes(fd, buffer, offset) {
 // Cache for PMTiles objects to avoid creating multiple instances for the same URL
 const pmtilesCache = new Map();
 
+/**
+ * Closes a PMTiles instance if it owns a closeable local file source.
+ * @param {PMTiles} pmtiles - The PMTiles instance to close.
+ * @returns {void}
+ */
+function closePMTiles(pmtiles) {
+  if (!pmtiles) {
+    return;
+  }
+
+  const source = pmtiles.source;
+  if (source && typeof source.close === 'function') {
+    source.close();
+  }
+}
+
 /**
  * Opens a PMTiles file from local filesystem, HTTP URL, or S3 URL.
  * Uses caching to avoid creating multiple PMTiles instances for the same file.
@@ -388,6 +421,17 @@ export function openPMtiles(
   return pmtiles;
 }
 
+/**
+ * Clears the PMTiles cache and closes any local file descriptors owned by cached sources.
+ * @returns {void}
+ */
+export function clearPMtilesCache() {
+  for (const pmtiles of pmtilesCache.values()) {
+    closePMTiles(pmtiles);
+  }
+  pmtilesCache.clear();
+}
+
 /**
  * Retrieves metadata and header information from a PMTiles archive with retry logic for rate limiting.
  * @param {PMTiles} pmtiles - The PMTiles instance.

package/src/serve_data.js

@@ -5,7 +5,7 @@ import path from 'path';
 
 import clone from 'clone';
 import express from 'express';
-import Pbf from 'pbf';
+import { PbfReader } from 'pbf';
 import { VectorTile } from '@mapbox/vector-tile';
 import { SphericalMercator } from '@mapbox/sphericalmercator';
 
@@ -21,6 +21,8 @@ import { gunzipP, gzipP } from './promises.js';
 import { openMbTilesWrapper } from './mbtiles_wrapper.js';
 
 import fs from 'node:fs';
+
+let metricsModule = null;
 import { fileURLToPath } from 'url';
 
 const packageJson = JSON.parse(
@@ -45,6 +47,16 @@ export const serve_data = {
    */
   init: function (options, repo, programOpts) {
     const { verbose, allowedHosts } = programOpts;
+    // Cache metrics module if enabled. Safe because tests verify before production.
+    if (programOpts.metrics) {
+      import('./metrics.js')
+        .then((m) => {
+          metricsModule = m;
+        })
+        .catch((err) => {
+          console.error('Failed to import metrics module:', err);
+        });
+    }
     const app = express().disable('x-powered-by');
     app.use(express.json());
 
@@ -142,7 +154,7 @@ export const serve_data = {
         headers['Content-Type'] = 'application/x-protobuf';
       } else if (format === 'geojson') {
         headers['Content-Type'] = 'application/json';
-        const tile = new VectorTile(new Pbf(data));
+        const tile = new VectorTile(new PbfReader(data));
         const geojson = {
           type: 'FeatureCollection',
           features: [],
@@ -167,6 +179,12 @@ export const serve_data = {
 
       data = await gzipP(data);
 
+      if (metricsModule) {
+        metricsModule.tilesServedTotal.inc({
+          type: 'vector',
+          name: req.params.id,
+        });
+      }
       return res.status(200).send(data);
     });
 
@@ -624,4 +642,29 @@ export const serve_data = {
       sparse,
     };
   },
+  /**
+   * Removes all items from the repository and closes owned local data sources.
+   * @param {object} repo Repository object.
+   * @returns {Promise<void>}
+   */
+  clear: async function (repo) {
+    await Promise.all(
+      Object.keys(repo).map(async (id) => {
+        // eslint-disable-next-line security/detect-object-injection -- id is from Object.keys() iteration
+        const item = repo[id];
+        try {
+          if (item && item.sourceType === 'mbtiles' && item.source) {
+            await new Promise((resolve, reject) => {
+              item.source.close((err) => (err ? reject(err) : resolve()));
+            });
+          }
+        } catch (err) {
+          console.warn(`Failed to close data source "${id}":`, err);
+        } finally {
+          // eslint-disable-next-line security/detect-object-injection -- id is from Object.keys() iteration
+          delete repo[id];
+        }
+      }),
+    );
+  },
 };

package/src/serve_font.js

@@ -4,6 +4,8 @@ import express from 'express';
 
 import { getFontsPbf, listFonts } from './utils.js';
 
+let metricsModule = null;
+
 /**
  * Initializes and returns an Express app that serves font files.
  * @param {object} options - Configuration options for the server.
@@ -13,6 +15,11 @@ import { getFontsPbf, listFonts } from './utils.js';
  */
 export async function serve_font(options, allowedFonts, programOpts) {
   const { verbose } = programOpts;
+  // Cache metrics module if enabled. Safe because tests verify before production.
+  if (programOpts.metrics) {
+    const m = await import('./metrics.js');
+    metricsModule = m;
+  }
   const app = express().disable('x-powered-by');
 
   const lastModified = new Date().toUTCString();
@@ -64,6 +71,9 @@ export async function serve_font(options, allowedFonts, programOpts) {
       );
       res.header('Content-type', 'application/x-protobuf');
       res.header('Last-Modified', lastModified);
+      if (metricsModule) {
+        metricsModule.tilesServedTotal.inc({ type: 'font', name: sFontStack });
+      }
       return res.send(concatenated);
     } catch (err) {
       console.error(

package/src/serve_rendered.js

@@ -539,6 +539,7 @@ function calcZForBBox(bbox, w, h, query) {
  * @param {object} res Express response object.
  * @param {Buffer|null} overlay Optional overlay image.
  * @param {string} mode Rendering mode ('tile' or 'static').
+ * @param {string|null} id Style or dataset ID for metrics labeling.
  * @returns {Promise<void>}
  */
 async function respondImage(
@@ -556,6 +557,7 @@ async function respondImage(
   res,
   overlay = null,
   mode = 'tile',
+  id = null,
 ) {
   if (
     Math.abs(lon) > 180 ||
@@ -599,10 +601,14 @@ async function respondImage(
   }
 
   pool.acquire(async (err, renderer) => {
+    const renderStart = process.hrtime.bigint();
     // Check if pool.acquire failed or returned null/invalid renderer
     if (err) {
       console.error('Failed to acquire renderer from pool:', err);
       if (!res.headersSent) {
+        if (metricsModule) {
+          metricsModule.tileErrorsTotal.inc({ type: 'rendered', name: id });
+        }
         return res.status(503).send('Renderer pool error');
       }
       return;
@@ -613,6 +619,9 @@ async function respondImage(
         'Renderer is null - likely crashed or failed to initialize',
       );
       if (!res.headersSent) {
+        if (metricsModule) {
+          metricsModule.tileErrorsTotal.inc({ type: 'rendered', name: id });
+        }
         return res.status(503).send('Renderer unavailable');
       }
       return;
@@ -627,6 +636,9 @@ async function respondImage(
         console.error('Error removing bad renderer:', e);
       }
       if (!res.headersSent) {
+        if (metricsModule) {
+          metricsModule.tileErrorsTotal.inc({ type: 'rendered', name: id });
+        }
         return res.status(503).send('Renderer invalid');
       }
       return;
@@ -693,6 +705,9 @@ async function respondImage(
             console.error('Error removing failed renderer:', e);
           }
           if (!res.headersSent) {
+            if (metricsModule) {
+              metricsModule.tileErrorsTotal.inc({ type: 'rendered', name: id });
+            }
             return res
               .status(500)
               .header('Content-Type', 'text/plain')
@@ -791,12 +806,34 @@ async function respondImage(
           if (err || !buffer) {
             console.error('Sharp error:', err);
             if (!res.headersSent) {
+              if (metricsModule) {
+                metricsModule.tileErrorsTotal.inc({
+                  type: 'rendered',
+                  name: id,
+                });
+              }
               return res.status(500).send('Image processing failed');
             }
             return;
           }
 
           if (!res.headersSent) {
+            if (metricsModule) {
+              const renderDurationSec =
+                Number(process.hrtime.bigint() - renderStart) / 1e9;
+              metricsModule.tilesServedTotal.inc({
+                type: 'rendered',
+                name: id,
+              });
+              const zoomLabel =
+                process.env.TILESERVER_GL_METRICS_ZOOM === 'true'
+                  ? String(z)
+                  : 'all';
+              metricsModule.tileRenderDuration.observe(
+                { name: id, zoom: zoomLabel },
+                renderDurationSec,
+              );
+            }
             res.set({
               'Last-Modified': item.lastModified,
               'Content-Type': `image/${format}`,
@@ -814,6 +851,9 @@ async function respondImage(
         console.error('Error removing renderer after error:', e);
       }
       if (!res.headersSent) {
+        if (metricsModule) {
+          metricsModule.tileErrorsTotal.inc({ type: 'rendered', name: id });
+        }
         return res.status(500).send('Render failed');
       }
     }
@@ -905,7 +945,7 @@ async function handleTileRequest(
 
   // prettier-ignore
   return await respondImage(
-    options, item, z, tileCenter[0], tileCenter[1], 0, 0, parsedTileSize, parsedTileSize, scale, format, res,
+    options, item, z, tileCenter[0], tileCenter[1], 0, 0, parsedTileSize, parsedTileSize, scale, format, res, null, 'tile', id,
   );
 }
 
@@ -1012,7 +1052,7 @@ async function handleStaticRequest(
 
     // prettier-ignore
     return await respondImage(
-    options, item, z, x, y, bearing, pitch, parsedWidth, parsedHeight, scale, format, res, overlay, 'static',
+    options, item, z, x, y, bearing, pitch, parsedWidth, parsedHeight, scale, format, res, overlay, 'static', id,
      );
   } else if (staticTypeMatch.groups.minx) {
     // Area Based Static Image
@@ -1052,7 +1092,7 @@ async function handleStaticRequest(
 
     // prettier-ignore
     return await respondImage(
-      options, item, z, x, y, bearing, pitch, parsedWidth, parsedHeight, scale, format, res, overlay, 'static',
+      options, item, z, x, y, bearing, pitch, parsedWidth, parsedHeight, scale, format, res, overlay, 'static', id,
      );
   } else if (staticTypeMatch.groups.auto) {
     // Area Static Image
@@ -1111,7 +1151,7 @@ async function handleStaticRequest(
 
     // prettier-ignore
     return await respondImage(
-        options, item, z, x, y, bearing, pitch, parsedWidth, parsedHeight, scale, format, res, overlay, 'static',
+        options, item, z, x, y, bearing, pitch, parsedWidth, parsedHeight, scale, format, res, overlay, 'static', id,
       );
   } else {
     return res.sendStatus(404);
@@ -1119,6 +1159,7 @@ async function handleStaticRequest(
 }
 const existingFonts = {};
 let maxScaleFactor = 2;
+let metricsModule = null;
 
 export const serve_rendered = {
   /**
@@ -1312,6 +1353,13 @@ export const serve_rendered = {
 
     const { publicUrl, verbose, fetchTimeout } = programOpts;
 
+    // Cache metrics module if enabled (avoids per-request dynamic imports).
+    // Guard prevents re-importing per style added. Safe because tests verify before production.
+    if (programOpts.metrics && !metricsModule) {
+      const m = await import('./metrics.js');
+      metricsModule = m;
+    }
+
     const styleJSON = clone(style);
 
     // Global sparse flag for HTTP/remote sources (from config options)
@@ -1857,6 +1905,31 @@ export const serve_rendered = {
         maxPoolSize,
       );
     }
+
+    if (metricsModule) {
+      map._metricsInterval = setInterval(() => {
+        [map.renderers, map.renderersStatic].forEach((poolArr) => {
+          poolArr.forEach((pool) => {
+            if (!pool) return;
+            try {
+              const total = pool.size ?? 0;
+              const available = pool.available ?? 0;
+              metricsModule.renderPoolSize.set({ name: id }, total);
+              metricsModule.renderPoolActive.set(
+                { name: id },
+                total - available,
+              );
+              metricsModule.renderPoolWaiting.set(
+                { name: id },
+                pool.pending ?? 0,
+              );
+            } catch (_) {
+              /* pool may be mid-teardown */
+            }
+          });
+        });
+      }, 5000);
+    }
   },
   /**
    * Removes an item from the repository.
@@ -1868,6 +1941,26 @@ export const serve_rendered = {
     // eslint-disable-next-line security/detect-object-injection -- id is function parameter for removal
     const item = repo[id];
     if (item) {
+      if (item.map._metricsInterval) {
+        clearInterval(item.map._metricsInterval);
+      }
+      Object.keys(item.map.sources || {}).forEach((sourceId) => {
+        // eslint-disable-next-line security/detect-object-injection -- sourceId is from Object.keys() iteration
+        const source = item.map.sources[sourceId];
+        // eslint-disable-next-line security/detect-object-injection -- sourceId is from Object.keys() iteration
+        const sourceType = item.map.sourceTypes[sourceId];
+        if (
+          sourceType === 'mbtiles' &&
+          source &&
+          typeof source.close === 'function'
+        ) {
+          source.close((err) => {
+            if (err) {
+              console.warn('Failed to close MBTiles source:', err);
+            }
+          });
+        }
+      });
       item.map.renderers.forEach((pool) => {
         pool.close();
       });
@@ -1879,25 +1972,59 @@ export const serve_rendered = {
     delete repo[id];
   },
   /**
-   * Removes all items from the repository.
+   * Removes all items from the repository and closes owned local data sources.
    * @param {object} repo Repository object.
-   * @returns {void}
+   * @returns {Promise<void>}
    */
-  clear: function (repo) {
-    Object.keys(repo).forEach((id) => {
-      // eslint-disable-next-line security/detect-object-injection -- id is from Object.keys() iteration
-      const item = repo[id];
-      if (item) {
-        item.map.renderers.forEach((pool) => {
-          pool.close();
-        });
-        item.map.renderersStatic.forEach((pool) => {
-          pool.close();
-        });
-      }
-      // eslint-disable-next-line security/detect-object-injection -- id is from Object.keys() iteration
-      delete repo[id];
-    });
+  clear: async function (repo) {
+    await Promise.all(
+      Object.keys(repo).map(async (id) => {
+        // eslint-disable-next-line security/detect-object-injection -- id is from Object.keys() iteration
+        const item = repo[id];
+        try {
+          if (!item) {
+            return;
+          }
+
+          await Promise.all(
+            Object.keys(item.map.sources || {}).map(async (sourceId) => {
+              // eslint-disable-next-line security/detect-object-injection -- sourceId is from Object.keys() iteration
+              const source = item.map.sources[sourceId];
+              // eslint-disable-next-line security/detect-object-injection -- sourceId is from Object.keys() iteration
+              const sourceType = item.map.sourceTypes[sourceId];
+              if (
+                sourceType === 'mbtiles' &&
+                source &&
+                typeof source.close === 'function'
+              ) {
+                await new Promise((resolve) => {
+                  source.close((err) => {
+                    if (err) {
+                      console.warn(
+                        `Failed to close MBTiles source "${sourceId}" while clearing rendered repo entry "${id}":`,
+                        err,
+                      );
+                    }
+                    resolve();
+                  });
+                });
+              }
+            }),
+          );
+          item.map.renderers.forEach((pool) => {
+            pool.close();
+          });
+          item.map.renderersStatic.forEach((pool) => {
+            pool.close();
+          });
+        } catch (err) {
+          console.warn(`Failed to clear rendered repo entry "${id}":`, err);
+        } finally {
+          // eslint-disable-next-line security/detect-object-injection -- id is from Object.keys() iteration
+          delete repo[id];
+        }
+      }),
+    );
   },
 
   /**

package/src/serve_style.js

@@ -14,6 +14,8 @@ import {
   isValidHttpUrl,
 } from './utils.js';
 
+let metricsModule = null;
+
 export const serve_style = {
   /**
    * Initializes the serve_style module.
@@ -24,6 +26,16 @@ export const serve_style = {
    */
   init: function (options, repo, programOpts) {
     const { verbose, allowedHosts } = programOpts;
+    // Cache metrics module if enabled. Safe because tests verify before production.
+    if (programOpts.metrics) {
+      import('./metrics.js')
+        .then((m) => {
+          metricsModule = m;
+        })
+        .catch((err) => {
+          console.error('Failed to import metrics module:', err);
+        });
+    }
     const app = express().disable('x-powered-by');
     /**
      * Handles requests for style.json files.
@@ -88,6 +100,9 @@ export const serve_style = {
             allowedHosts,
           );
         }
+        if (metricsModule) {
+          metricsModule.tilesServedTotal.inc({ type: 'style', name: id });
+        }
         return res.send(styleJSON_);
       } catch (e) {
         next(e);

package/src/server.js

@@ -16,6 +16,7 @@ import morgan from 'morgan';
 import { serve_data } from './serve_data.js';
 import { serve_style } from './serve_style.js';
 import { serve_font } from './serve_font.js';
+import { clearPMtilesCache } from './pmtiles_adapter.js';
 import {
   allowedTileSizes,
   getTileUrls,
@@ -45,6 +46,7 @@ const { serve_rendered } = await import(
  * @returns {Promise<object>} - A promise that resolves to the server object.
  */
 async function start(opts) {
+  let metricsModule = null;
   console.log('Starting server');
 
   const app = express().disable('x-powered-by');
@@ -54,9 +56,41 @@ async function start(opts) {
     data: {},
     fonts: {},
   };
+  let cleanup = async () => {};
 
   app.enable('trust proxy');
 
+  // Import metrics module early if enabled, so middleware doesn't miss requests
+  if (opts.metrics) {
+    try {
+      const m = await import('./metrics.js');
+      metricsModule = m;
+    } catch (err) {
+      console.warn(`[metrics] Failed to import metrics module: ${err.message}`);
+    }
+  }
+
+  // Prometheus HTTP metrics middleware (only register if metrics enabled)
+  if (opts.metrics) {
+    app.use((req, res, next) => {
+      const start = process.hrtime.bigint();
+      res.on('finish', () => {
+        const route = req.route?.path ?? '<unknown>';
+        const durationSec = Number(process.hrtime.bigint() - start) / 1e9;
+        metricsModule.httpRequestsTotal.inc({
+          method: req.method,
+          route,
+          status_code: String(res.statusCode),
+        });
+        metricsModule.httpRequestDuration.observe(
+          { method: req.method, route, status_code: String(res.statusCode) },
+          durationSec,
+        );
+      });
+      next();
+    });
+  }
+
   if (process.env.NODE_ENV !== 'test') {
     const defaultLogFormat =
       process.env.NODE_ENV === 'production' ? 'tiny' : 'dev';
@@ -502,6 +536,10 @@ async function start(opts) {
       continue;
     }
     stylePromises.push(addStyle(id, item, true, true));
+    // Pre-initialize error counter for this style so metric appears in output
+    if (metricsModule) {
+      metricsModule.tileErrorsTotal.inc({ type: 'rendered', name: id }, 0);
+    }
   }
 
   // Wait for styles to finish loading, then load data sources
@@ -553,6 +591,9 @@ async function start(opts) {
       path.join(options.paths.styles, '*.json'),
       {},
     );
+    cleanup = async () => {
+      await watcher.close();
+    };
     watcher.on('all', (eventType, filename) => {
       if (filename) {
         const id = path.basename(filename, '.json');
@@ -913,26 +954,12 @@ async function start(opts) {
       return null;
     }
 
-    let baseUrl;
-    if (opts.publicUrl) {
-      baseUrl = opts.publicUrl;
-    } else {
-      const parsedAllowed = parseAllowedHosts(opts.allowedHosts);
-      const candidateHost = getCandidateHost(req);
-      if (!isHostAllowed(candidateHost, parsedAllowed)) {
-        baseUrl = '/';
-      } else {
-        const proto = getSafeProtocol(req);
-        baseUrl = `${proto}://${candidateHost}/`;
-      }
-    }
-
     return {
       ...wmts,
       id,
       // eslint-disable-next-line security/detect-object-injection -- id is route parameter from URL
       name: (serving.styles[id] || serving.rendered[id]).name,
-      baseUrl,
+      baseUrl: getPublicUrl(opts.publicUrl, req, opts.allowedHosts),
     };
   });
 
@@ -1026,11 +1053,40 @@ async function start(opts) {
   // add server.shutdown() to gracefully stop serving
   enableShutdown(server);
 
+  // Prometheus metrics server (separate port, opt-in)
+  let metricsServer = null;
+  if (opts.metrics && metricsModule) {
+    try {
+      const metricsApp = express();
+      metricsApp.get('/metrics', async (_req, res) => {
+        res.set('Content-Type', metricsModule.registry.contentType);
+        res.end(await metricsModule.registry.metrics());
+      });
+      await new Promise((resolve) => {
+        metricsServer = metricsApp.listen(opts.metricsPort, '127.0.0.1');
+        metricsServer.once('error', (err) => {
+          console.warn(
+            `[metrics] Failed to start metrics server: ${err.message}`,
+          );
+          resolve(); // don't crash — metrics are non-critical
+        });
+        metricsServer.once('listening', resolve);
+      });
+      console.log(
+        `Prometheus metrics available at http://localhost:${opts.metricsPort}/metrics`,
+      );
+    } catch (err) {
+      console.warn(`[metrics] Failed to initialize metrics: ${err.message}`);
+    }
+  }
+
   return {
     app,
     server,
     startupPromise,
     serving,
+    cleanup,
+    metricsServer,
   };
 }
 /**
@@ -1043,6 +1099,17 @@ function stopGracefully(signal) {
   process.exit();
 }
 
+/**
+ * Registers a process signal handler once.
+ * @param {string} signal Name of the process signal.
+ * @returns {void}
+ */
+function registerSignalHandler(signal) {
+  if (!process.listeners(signal).includes(stopGracefully)) {
+    process.on(signal, stopGracefully);
+  }
+}
+
 /**
  * Starts and manages the server
  * @param {object} opts - Configuration options for the server.
@@ -1050,28 +1117,72 @@ function stopGracefully(signal) {
  */
 export async function server(opts) {
   const running = await start(opts);
+  let reloading = false;
+  let pendingReload = false;
 
   running.startupPromise.catch((err) => {
     console.error(err.message);
     process.exit(1);
   });
 
-  process.on('SIGINT', stopGracefully);
-  process.on('SIGTERM', stopGracefully);
+  registerSignalHandler('SIGINT');
+  registerSignalHandler('SIGTERM');
+
+  const reload = async () => {
+    if (reloading) {
+      pendingReload = true;
+      console.log('Reload already in progress, queueing another refresh');
+      return;
+    }
+
+    reloading = true;
+    let reloadAgain = true;
+
+    try {
+      while (reloadAgain) {
+        reloadAgain = false;
+        pendingReload = false;
+        await new Promise((resolve, reject) => {
+          running.server.shutdown((err) => {
+            if (err) {
+              reject(err);
+              return;
+            }
+            resolve();
+          });
+        });
+        if (running.metricsServer) {
+          await new Promise((resolve) => running.metricsServer.close(resolve));
+        }
+        await running.cleanup();
+        await serve_data.clear(running.serving.data);
+        if (!isLight) {
+          await serve_rendered.clear(running.serving.rendered);
+        }
+        clearPMtilesCache();
+
+        const restarted = await start(opts);
+        running.server = restarted.server;
+        running.app = restarted.app;
+        running.startupPromise = restarted.startupPromise;
+        running.serving = restarted.serving;
+        running.cleanup = restarted.cleanup;
+        running.metricsServer = restarted.metricsServer;
+        await running.startupPromise;
+        reloadAgain = pendingReload;
+      }
+    } finally {
+      reloading = false;
+    }
+  };
 
   process.on('SIGHUP', (signal) => {
     console.log(`Caught signal ${signal}, refreshing`);
     console.log('Stopping server and reloading config');
 
-    running.server.shutdown(async () => {
-      const restarted = await start(opts);
-      if (!isLight) {
-        serve_rendered.clear(running.serving.rendered);
-      }
-      running.server = restarted.server;
-      running.app = restarted.app;
-      running.startupPromise = restarted.startupPromise;
-      running.serving = restarted.serving;
+    reload().catch((err) => {
+      console.error(err.message);
+      process.exit(1);
     });
   });
   return running;

package/test/fixtures/reload-config.json

@@ -0,0 +1,34 @@
+{
+  "options": {
+    "serveAllStyles": true,
+    "paths": {
+      "root": "../../test_data",
+      "fonts": "fonts",
+      "styles": "styles"
+    }
+  },
+  "styles": {
+    "test-style": {
+      "style": "osm-bright/style.json",
+      "tilejson": {
+        "type": "overlay",
+        "bounds": [8.529446, 47.364758, 8.55232, 47.380539]
+      }
+    },
+    "maptiler-basic": {
+      "style": "maptiler-basic/style.json",
+      "tilejson": {
+        "type": "overlay",
+        "bounds": [8.529446, 47.364758, 8.55232, 47.380539]
+      }
+    }
+  },
+  "data": {
+    "openmaptiles": {
+      "mbtiles": "zurich_switzerland.mbtiles"
+    },
+    "terrain": {
+      "mbtiles": "terrain.mbtiles"
+    }
+  }
+}

package/test/metrics.js

@@ -0,0 +1,102 @@
+'use strict';
+
+import { expect } from 'chai';
+import { server } from '../src/server.js';
+import http from 'node:http';
+
+/**
+ * Helper: GET a URL, returns { statusCode, headers, body }
+ * @param {string} url URL to fetch
+ * @returns {Promise<{statusCode: number, headers: object, body: string}>} Response object
+ */
+function httpGet(url) {
+  return new Promise((resolve, reject) => {
+    http
+      .get(url, (res) => {
+        let body = '';
+        res.on('data', (chunk) => (body += chunk));
+        res.on('end', () =>
+          resolve({ statusCode: res.statusCode, headers: res.headers, body }),
+        );
+      })
+      .on('error', reject);
+  });
+}
+
+describe('Prometheus metrics', function () {
+  this.timeout(15000);
+
+  let metricsServer;
+  let tileServer;
+
+  before(async function () {
+    const running = await server({
+      configPath: 'config.json',
+      port: 8889,
+      publicUrl: '/test/',
+      metrics: true,
+      metricsPort: 9999,
+    });
+    tileServer = running.server;
+    metricsServer = running.metricsServer;
+    // give metrics server a moment if needed
+    await new Promise((r) => setTimeout(r, 100));
+  });
+
+  after(function () {
+    tileServer?.close();
+    metricsServer?.close();
+  });
+
+  it('GET /metrics returns 200 with text/plain content type', async function () {
+    const { statusCode, headers } = await httpGet(
+      'http://localhost:9999/metrics',
+    );
+    expect(statusCode).to.equal(200);
+    expect(headers['content-type']).to.include('text/plain');
+  });
+
+  it('GET /metrics body includes expected metric names', async function () {
+    const { body } = await httpGet('http://localhost:9999/metrics');
+    expect(body).to.include('tileserver_http_requests_total');
+    expect(body).to.include('tileserver_tiles_served_total');
+    expect(body).to.include('tileserver_render_pool_size');
+  });
+
+  it('making a request increments tileserver_http_requests_total', async function () {
+    await httpGet('http://localhost:8889/test/health');
+    const { body } = await httpGet('http://localhost:9999/metrics');
+    const match = body.match(/tileserver_http_requests_total\{[^}]+\}\s+(\d+)/);
+    expect(match).to.not.equal(null);
+    expect(parseInt(match[1], 10)).to.be.greaterThan(0);
+  });
+
+  it('metrics server does NOT start when metrics: false', function (done) {
+    server({
+      configPath: 'config.json',
+      port: 8890,
+      publicUrl: '/test/',
+      metrics: false,
+      metricsPort: 9998,
+    })
+      .then((running) => {
+        running.startupPromise
+          .then(() => {
+            setTimeout(() => {
+              http
+                .get('http://localhost:9998/metrics', () => {
+                  running.server.close();
+                  done(new Error('Should not have connected'));
+                })
+                .on('error', (err) => {
+                  running.server.close();
+                  expect(err.code).to.equal('ECONNREFUSED');
+                  done();
+                });
+            }, 200);
+          })
+          .catch(done);
+      })
+      .catch(done);
+  });
+});

package/test/reload.js

@@ -0,0 +1,98 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { server } from '../src/server.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Returns listeners added after a previous listener count.
+ * @param {string} eventName Process event name.
+ * @param {number} previousListenerCount Previously registered listener count.
+ * @returns {Array<(...args: unknown[]) => void>} Newly registered listeners.
+ */
+function getAddedListeners(eventName, previousListenerCount) {
+  return process.listeners(eventName).slice(previousListenerCount);
+}
+
+/**
+ * Waits until a condition becomes true.
+ * @param {() => boolean} condition Predicate to check.
+ * @param {number} [timeoutMs] Maximum wait time.
+ * @returns {Promise<void>}
+ */
+async function waitFor(condition, timeoutMs = 5000) {
+  const startedAt = Date.now();
+
+  while (Date.now() - startedAt < timeoutMs) {
+    if (condition()) {
+      return;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+
+  throw new Error('Timed out waiting for condition');
+}
+
+describe('SIGHUP reload', function () {
+  it('runs runtime cleanup before replacing the server generation', async function () {
+    const previousListeners = [
+      {
+        eventName: 'SIGHUP',
+        listenerCount: process.listeners('SIGHUP').length,
+      },
+      {
+        eventName: 'SIGINT',
+        listenerCount: process.listeners('SIGINT').length,
+      },
+      {
+        eventName: 'SIGTERM',
+        listenerCount: process.listeners('SIGTERM').length,
+      },
+    ];
+    let running;
+
+    try {
+      running = await server({
+        configPath: path.join(__dirname, 'fixtures/reload-config.json'),
+        port: 0,
+        publicUrl: '/test/',
+      });
+      await running.startupPromise;
+
+      const reloadListeners = getAddedListeners(
+        'SIGHUP',
+        previousListeners[0].listenerCount,
+      );
+      expect(reloadListeners).to.have.lengthOf(1);
+
+      let cleanupCalls = 0;
+      const cleanup = running.cleanup;
+      running.cleanup = async () => {
+        cleanupCalls += 1;
+        await cleanup();
+      };
+
+      const startupPromise = running.startupPromise;
+      reloadListeners[0]('SIGHUP');
+
+      await waitFor(() => running.startupPromise !== startupPromise);
+      await running.startupPromise;
+
+      expect(cleanupCalls).to.equal(1);
+    } finally {
+      if (running) {
+        await running.cleanup();
+        if (running.server.listening) {
+          await new Promise((resolve) => running.server.close(resolve));
+        }
+      }
+
+      for (const { eventName, listenerCount } of previousListeners) {
+        for (const listener of getAddedListeners(eventName, listenerCount)) {
+          process.removeListener(eventName, listener);
+        }
+      }
+    }
+  });
+});

package/test/style.js

@@ -53,6 +53,42 @@ describe('Styles', function () {
   });
 });
 
+describe('WMTS', function () {
+  describe('/styles/' + prefix + '/wmts.xml', function () {
+    testIs('/styles/' + prefix + '/wmts.xml', /text\/xml/);
+
+    it('contains a valid absolute baseUrl using public_url', function (done) {
+      supertest(app)
+        .get('/styles/' + prefix + '/wmts.xml')
+        .expect(function (res) {
+          // The server is started with publicUrl: '/test/' in setup.js.
+          // getPublicUrl resolves a relative publicUrl against the request host,
+          // so all URLs in the document must be absolute (not just '/test/').
+          expect(res.text).to.not.include('href="/test/');
+          expect(res.text).to.include('href="http://');
+          expect(res.text).to.include('/test/styles/' + prefix + '/wmts.xml');
+        })
+        .end(done);
+    });
+
+    it('contains valid absolute tile resource URLs using public_url', function (done) {
+      supertest(app)
+        .get('/styles/' + prefix + '/wmts.xml')
+        .expect(function (res) {
+          expect(res.text).to.not.include('template="/test/');
+          expect(res.text).to.include('template="http://');
+          expect(res.text).to.include('/test/styles/' + prefix + '/256/');
+          expect(res.text).to.include('/test/styles/' + prefix + '/512/');
+        })
+        .end(done);
+    });
+  });
+
+  describe('/styles/non_existent/wmts.xml returns 404', function () {
+    testIs('/styles/non_existent/wmts.xml', /./, 404);
+  });
+});
+
 describe('Fonts', function () {
   testIs('/fonts/Open Sans Bold/0-255.pbf', /application\/x-protobuf/);
   testIs('/fonts/Open Sans Regular/65280-65535.pbf', /application\/x-protobuf/);