chiitiler 1.23.8 → 1.24.1

package/README.md

@@ -158,10 +158,12 @@ 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
 
@@ -170,6 +172,8 @@ Prewarm is enabled by default: one tile is rendered at startup **before** the se
 | `--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` |
+| `--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` |
@@ -183,6 +187,33 @@ Prewarm is enabled by default: one tile is rendered at startup **before** the se
 
 Chiitiler caches *source assets* (vector tiles, glyphs, sprites) — not final rasters — so cached data is reused across requests. Standard AWS / GCP credentials (`AWS_ACCESS_KEY_ID`, `GOOGLE_APPLICATION_CREDENTIALS`, etc.) are respected.
 
+The tile server adds a per-process memory front cache to `file`, `s3`, and `gcs`:
+by default, buffers are retained for 10 seconds from insertion, with an LRU limit of 64 MiB
+of buffer payloads (JavaScript overhead is additional). Reads promote backing-cache
+hits into memory; writes populate memory immediately and also write to the backing
+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 `--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.
+
+The front-cache TTL does not guarantee source freshness: promotion can retain a
+value for up to the configured TTL beyond its backing-cache expiry, and the S3/GCS cache
+implementations do not check expiry on reads. Each worker has its own memory limit.
+Library callers can opt in and customize the limits (either limit set to `0`
+returns the backing cache unchanged):
+
+```ts
+const cache = ChiitilerCache.withMemoryCache(
+    ChiitilerCache.fileCache({ dir: './.cache', ttl: 3600 }),
+    { ttlSeconds: 10, maxBytes: 64 * 1024 * 1024 },
+);
+```
+
 ## Deployment
 
 - **Docker** — `ghcr.io/kanahiro/chiitiler:latest` (entrypoint: `tile-server`)

package/dist/cache/front.d.ts

@@ -0,0 +1,11 @@
+import type { Cache } from './index.js';
+/**
+ * Keep recent source buffers in this process to avoid backing-cache I/O.
+ * TTL starts on insertion, so promotion can extend the backing cache's lifetime
+ * by up to ttlSeconds. maxBytes bounds buffer payloads, not total process memory.
+ * Either limit set to zero disables the front cache and returns backing unchanged.
+ */
+export declare function withMemoryCache(backing: Cache, { ttlSeconds, maxBytes }?: {
+    ttlSeconds?: number | undefined;
+    maxBytes?: number | undefined;
+}): Cache;

package/dist/cache/front.js

@@ -0,0 +1,52 @@
+import { LRUCache } from 'lru-cache';
+/**
+ * Keep recent source buffers in this process to avoid backing-cache I/O.
+ * TTL starts on insertion, so promotion can extend the backing cache's lifetime
+ * by up to ttlSeconds. maxBytes bounds buffer payloads, not total process memory.
+ * Either limit set to zero disables the front cache and returns backing unchanged.
+ */
+export function withMemoryCache(backing, { ttlSeconds = 10, maxBytes = 64 * 1024 * 1024 } = {}) {
+    if (ttlSeconds === 0 || maxBytes === 0)
+        return backing;
+    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+        throw new Error('ttlSeconds must be positive and finite');
+    }
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+        throw new Error('maxBytes must be a positive safe integer');
+    }
+    const memory = new LRUCache({
+        maxSize: maxBytes,
+        sizeCalculation: (value) => Math.max(1, value.byteLength),
+        ttl: ttlSeconds * 1000,
+        ttlResolution: 0,
+    });
+    const reads = new Map();
+    return {
+        name: backing.name,
+        get: async (key) => {
+            const hit = memory.get(key);
+            if (hit !== undefined)
+                return hit;
+            const pending = reads.get(key);
+            if (pending !== undefined)
+                return pending;
+            const read = backing.get(key).then((value) => {
+                // A newer write must not be overwritten by an older read.
+                if (value !== undefined && reads.get(key) === read)
+                    memory.set(key, value);
+                return value;
+            }).finally(() => {
+                if (reads.get(key) === read)
+                    reads.delete(key);
+            });
+            reads.set(key, read);
+            return read;
+        },
+        set: async (key, value) => {
+            reads.delete(key);
+            // Populate before awaiting persistence; callers may not await set.
+            memory.set(key, value);
+            await backing.set(key, value);
+        },
+    };
+}

package/dist/cache/index.d.ts

@@ -2,6 +2,7 @@ import { memoryCache } from './memory.js';
 import { s3Cache } from './s3.js';
 import { gcsCache } from './gcs.js';
 import { fileCache } from './file.js';
+export { withMemoryCache } from './front.js';
 type Value = Buffer;
 type Cache = {
     name: string;

package/dist/cache/index.js

@@ -2,6 +2,7 @@ import { memoryCache } from './memory.js';
 import { s3Cache } from './s3.js';
 import { gcsCache } from './gcs.js';
 import { fileCache } from './file.js';
+export { withMemoryCache } from './front.js';
 const noneCache = () => ({
     name: 'none',
     get: async () => undefined,

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);
@@ -130,6 +149,14 @@ export function createProgram() {
             port: parsePort(options.port),
             debug: parseDebug(options.debug),
         };
+        if (['file', 's3', 'gcs'].includes(serverOptions.cache.name)) {
+            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),
+            });
+        }
         if (serverOptions.debug) {
             console.log(`running server: http://localhost:${serverOptions.port}`);
             console.log(`cache method: ${serverOptions.cache.name}`);
@@ -139,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/package.json

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