tileserver-gl 5.6.0 → 5.7.0-pre.0

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);
@@ -246,6 +261,8 @@ export const serve_style = {
           // eslint-disable-next-line security/detect-object-injection -- name is from Object.keys of styleForValidation.sources
           styleForValidation.sources[name] &&
           // eslint-disable-next-line security/detect-object-injection -- name is from Object.keys of styleForValidation.sources
+          typeof styleForValidation.sources[name] === 'object' &&
+          // eslint-disable-next-line security/detect-object-injection -- name is from Object.keys of styleForValidation.sources
           'sparse' in styleForValidation.sources[name]
         ) {
           try {

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';
@@ -249,10 +283,12 @@ async function start(opts) {
             // eslint-disable-next-line security/detect-object-injection -- dataItemId is validated above
             const dataSource = data[dataItemId];
             const fileType = dataSource.pmtiles ? 'pmtiles' : 'mbtiles';
+            // eslint-disable-next-line security/detect-object-injection -- fileType is either 'pmtiles' or 'mbtiles'
             const fileName = dataSource[fileType];
 
             // Skip validation for remote URLs
             if (fileName && !isValidRemoteUrl(fileName)) {
+              // eslint-disable-next-line security/detect-object-injection -- fileType is either 'pmtiles' or 'mbtiles'
               const filePath = path.resolve(options.paths[fileType], fileName);
               try {
                 const stats = fs.statSync(filePath);
@@ -264,7 +300,7 @@ async function start(opts) {
                   // File missing but flag not set - let it fail later
                   return dataItemId;
                 }
-              } catch (err) {
+              } catch (_err) {
                 // File doesn't exist
                 if (opts.ignoreMissingFiles) {
                   return undefined;
@@ -299,7 +335,7 @@ async function start(opts) {
                       return undefined;
                     }
                   }
-                } catch (err) {
+                } catch (_err) {
                   // File doesn't exist
                   if (opts.ignoreMissingFiles) {
                     return undefined;
@@ -500,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
@@ -551,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');
@@ -613,7 +656,7 @@ async function start(opts) {
     for (const id of Object.keys(serving[type])) {
       // eslint-disable-next-line security/detect-object-injection -- type is 'rendered' or 'data', id is from Object.keys
       const info = clone(serving[type][id].tileJSON);
-      let path = '';
+      let path;
       if (type === 'rendered') {
         path = `styles/${id}`;
       } else {
@@ -711,7 +754,7 @@ async function start(opts) {
         if (opts.verbose >= 1) {
           console.log(`Serving template at path: ${urlPath}`);
         }
-        let data = {};
+        let data;
         if (dataGetter) {
           data = dataGetter(req);
           if (data) {
@@ -738,7 +781,7 @@ async function start(opts) {
       });
     } catch (err) {
       console.error(`Error reading template file: ${templateFile}`, err);
-      throw new Error(`Template not found: ${err.message}`); //throw an error so that the server doesnt start
+      throw new Error(`Template not found: ${err.message}`, { cause: err }); //throw an error so that the server doesnt start
     }
   }
 
@@ -911,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),
     };
   });
 
@@ -1024,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,
   };
 }
 /**
@@ -1041,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.
@@ -1048,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/src/utils.js

@@ -138,7 +138,7 @@ export function parseAllowedHosts(allowedHosts) {
  * Returns true if host is allowed (allowlist is "*" or host is in the list). Port stripped, comparison case-insensitive.
  * @param {string} host - Host to check (e.g. from request or X-Forwarded-Host).
  * @param {string|string[]} allowedHosts - Result of parseAllowedHosts().
- * @returns {boolean}
+ * @returns {boolean} - True if the host is allowed, false otherwise.
  */
 export function isHostAllowed(host, allowedHosts) {
   if (!host || typeof host !== 'string') {
@@ -161,7 +161,7 @@ const BAD_HOST_RE = /[\s/]/;
  * Candidate host from request: X-Forwarded-Host or Host header.
  * Returns undefined if the value looks malformed (contains / or whitespace), so it is treated as not allowed.
  * @param {object} req - Express request.
- * @returns {string|undefined}
+ * @returns {string|undefined} - The candidate host string, or undefined if the value is malformed.
  */
 export function getCandidateHost(req) {
   const check = (raw) => {
@@ -475,7 +475,7 @@ async function getFontPbf(allowedFonts, fontPath, name, range, fallbacks) {
         delete fallbacks[fallbackName];
         return getFontPbf(null, fontPath, fallbackName, range, fallbacks);
       } else {
-        throw new Error('Font load error');
+        throw new Error('Font load error', { cause: err });
       }
     }
   } else {

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/);