chiitiler 1.23.8 → 1.24.0

package/README.md

@@ -170,6 +170,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` |
+| — | `CHIITILER_FRONT_CACHE_TTL_SEC` | `10` (seconds) |
+| — | `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 +185,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 `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
+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

@@ -130,6 +130,14 @@ export function createProgram() {
             port: parsePort(options.port),
             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;
+            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}`);

package/package.json

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