chiitiler 1.24.0 → 1.24.2

package/README.md

@@ -158,20 +158,27 @@ All options can be set via CLI flag or environment variable.
 | `--port <n>` | `CHIITILER_PORT` | `3000` |
 | `--debug` | `CHIITILER_DEBUG` | `false` |
 | `--user-agent <ua>` | `CHIITILER_USER_AGENT` | (none) |
-| — | `CHIITILER_PREWARM` | `true` |
-| — | `CHIITILER_PROCESSES` | `1` (set `0` for all CPUs) |
+| `--prewarm [true\|false]` | `CHIITILER_PREWARM` | `true` |
+| `--processes <n>` | `CHIITILER_PROCESSES` | `1` (set `0` for all CPUs) |
 
-Prewarm is enabled by default: one tile is rendered at startup **before** the server starts listening, moving shared renderer initialization work into startup. Either `--no-prewarm` or `CHIITILER_PREWARM=false` disables it. Style-specific tiles, glyphs, and sprites are not preloaded.
+Prewarm is enabled by default: one tile is rendered at startup **before** the server starts listening, moving shared renderer initialization work into startup. `--prewarm false` or `CHIITILER_PREWARM=false` disables it. `--prewarm` alone enables it. The CLI flag takes precedence over the environment variable. Style-specific tiles, glyphs, and sprites are not preloaded.
+
+`--processes` takes precedence over `CHIITILER_PROCESSES` and accepts non-negative integers; `0` uses all available CPUs.
 
 ### Cache
 
+Renderer Maps are reused per style and rendering mode without an idle timeout.
+They are released when their pool is evicted from the 10-entry LRU or explicitly
+closed. This avoids repeated initialization after quiet periods, at the cost of
+retaining native renderer memory between requests.
+
 | Flag | Env | Default |
 | --- | --- | --- |
 | `--cache <none\|memory\|file\|s3\|gcs>` | `CHIITILER_CACHE_METHOD` | `none` |
 | `--cache-ttl <seconds>` | `CHIITILER_CACHE_TTL_SEC` | `3600` |
 | `--memory-cache-max-item-count <n>` | `CHIITILER_MEMORYCACHE_MAXITEMCOUNT` | `1000` |
-| — | `CHIITILER_FRONT_CACHE_TTL_SEC` | `10` (seconds) |
-| — | `CHIITILER_FRONT_CACHE_MAX_BYTES` | `67108864` (64 MiB) |
+| `--front-cache-ttl-sec <seconds>` | `CHIITILER_FRONT_CACHE_TTL_SEC` | `10` (seconds) |
+| `--front-cache-max-bytes <bytes>` | `CHIITILER_FRONT_CACHE_MAX_BYTES` | `67108864` (64 MiB) |
 | `--file-cache-dir <dir>` | `CHIITILER_FILECACHE_DIR` | `./.cache` |
 | `--s3-cache-bucket <name>` | `CHIITILER_S3CACHE_BUCKET` | — |
 | `--s3-region <region>` | `CHIITILER_S3_REGION` | `us-east-1` |
@@ -192,9 +199,9 @@ hits into memory; writes populate memory immediately and also write to the backi
 cache. `none` and `memory` keep their existing behavior. This affects sources that
 already use the cache, not direct `s3://`, `gs://`, or local source reads.
 
-Set `CHIITILER_FRONT_CACHE_TTL_SEC` to a positive, finite number of seconds and
-`CHIITILER_FRONT_CACHE_MAX_BYTES` to a positive integer number of bytes to override
-these limits. Setting either variable to `0` disables the front cache and uses the
+Set `--front-cache-ttl-sec` / `CHIITILER_FRONT_CACHE_TTL_SEC` to a positive, finite number of seconds and
+`--front-cache-max-bytes` / `CHIITILER_FRONT_CACHE_MAX_BYTES` to a positive integer number of bytes to override
+these limits. CLI flags take precedence over environment variables. Setting either limit to `0` disables the front cache and uses the
 backing cache directly. Otherwise, invalid values stop startup when using `file`,
 `s3`, or `gcs`.
 These settings do not affect `none`, `memory`, or library callers.

package/dist/cli.js

@@ -1,5 +1,7 @@
 import process from 'node:process';
-import { Command } from 'commander';
+import cluster from 'node:cluster';
+import { availableParallelism } from 'node:os';
+import { Command, Option, InvalidArgumentError } from 'commander';
 import { initServer } from './server/index.js';
 import * as caches from './cache/index.js';
 import { setUserAgent } from './source/userAgent.js';
@@ -72,9 +74,12 @@ function parsePort(port) {
     // undefined or invalid
     return 3000;
 }
-function parsePrewarm(prewarmFlag) {
-    // Commander defaults a negated option to true; either opt-out disables warmup.
-    return prewarmFlag !== false && process.env.CHIITILER_PREWARM !== 'false';
+function parseProcesses(value) {
+    const count = Number(value.trim() || NaN);
+    if (!Number.isSafeInteger(count) || count < 0) {
+        throw new InvalidArgumentError('processes must be a non-negative safe integer');
+    }
+    return count;
 }
 function parseDebug(debug) {
     // command-line option
@@ -106,9 +111,23 @@ export function createProgram() {
         .option('--gcs-api-endpoint <api-endpoint>', 'gcs api endpoint', '')
         .option('-p, --port <port>', 'port number')
         .option('--user-agent <user-agent>', 'User-Agent header for outbound HTTP requests')
-        .option('--no-prewarm', 'disable startup renderer warmup (enabled by default)')
+        .addOption(new Option('--prewarm [boolean]', 'startup renderer warmup')
+        .choices(['true', 'false']).preset('true').env('CHIITILER_PREWARM').default('true'))
+        .addOption(new Option('--processes <n>', 'worker processes (0 for all CPUs)')
+        .env('CHIITILER_PROCESSES').argParser(parseProcesses).default(1))
+        .addOption(new Option('--front-cache-ttl-sec <seconds>', 'memory front cache TTL (0 to disable)')
+        .env('CHIITILER_FRONT_CACHE_TTL_SEC'))
+        .addOption(new Option('--front-cache-max-bytes <bytes>', 'memory front cache byte limit (0 to disable)')
+        .env('CHIITILER_FRONT_CACHE_MAX_BYTES'))
         .option('-D, --debug', 'debug mode')
         .action(async (options) => {
+        const numProcesses = options.processes === 0 ? availableParallelism() : options.processes;
+        if (cluster.isPrimary && numProcesses !== 1) {
+            // Workers inherit argv and env, and initialize their own renderer and cache.
+            for (let i = 0; i < numProcesses; i++)
+                cluster.fork();
+            return;
+        }
         // env fallback (CHIITILER_USER_AGENT) is handled in userAgent.ts
         if (options.userAgent !== undefined)
             setUserAgent(options.userAgent);
@@ -131,8 +150,8 @@ export function createProgram() {
             debug: parseDebug(options.debug),
         };
         if (['file', 's3', 'gcs'].includes(serverOptions.cache.name)) {
-            const ttl = process.env.CHIITILER_FRONT_CACHE_TTL_SEC;
-            const size = process.env.CHIITILER_FRONT_CACHE_MAX_BYTES;
+            const ttl = options.frontCacheTtlSec;
+            const size = options.frontCacheMaxBytes;
             serverOptions.cache = caches.withMemoryCache(serverOptions.cache, {
                 ttlSeconds: ttl === undefined ? undefined : Number(ttl.trim() || NaN),
                 maxBytes: size === undefined ? undefined : Number(size.trim() || NaN),
@@ -147,7 +166,7 @@ export function createProgram() {
         // warm up BEFORE listening: Lambda Web Adapter polls the
         // readiness check until the port opens, so work done here
         // stays inside the INIT phase (full CPU boost)
-        if (parsePrewarm(options.prewarm)) {
+        if (options.prewarm === 'true') {
             const startedAt = Date.now();
             try {
                 await prewarm(serverOptions.cache);

package/dist/main.js

@@ -1,22 +1,6 @@
-import cluster from 'node:cluster';
-import { availableParallelism } from 'node:os';
 import process from 'node:process';
 import { createProgram } from './cli.js';
-const program = createProgram();
-const numProcesses = (() => {
-    if (process.env.CHIITILER_PROCESSES === undefined)
-        return 1;
-    const processesEnv = Number(process.env.CHIITILER_PROCESSES);
-    if (processesEnv === 0)
-        return availableParallelism();
-    else
-        return processesEnv;
-})();
-if (cluster.isPrimary && numProcesses !== 1) {
-    // Fork workers.
-    for (let i = 0; i < numProcesses; i++)
-        cluster.fork();
-}
-else {
-    program.parse(process.argv);
-}
+createProgram().parseAsync(process.argv).catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/dist/render/pool.js

@@ -50,6 +50,10 @@ async function getRenderPool(style, cache, mode) {
         destroy: (map) => {
             map.release();
         },
+    }, {
+        // Keep initialized Maps until their pool is evicted or closed. Disable
+        // idle housekeeping rather than running a timer in warm Lambda environments.
+        houseKeepInterval: 0,
     });
     mapPoolCache.set(cacheKey, newPool);
     return newPool;

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "chiitiler",
-  "version": "1.24.0",
+  "version": "1.24.2",
   "description": "Tiny map rendering server for MapLibre Style Spec",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",