jskelet 0.6.2 → 0.6.4

package/types/config/defaults.d.ts

@@ -131,6 +131,12 @@ export declare const CLASSIC_PREWARM_KEYS: string[];
  * `vary.host` kopyası sayı tavanının altında da RSS'i şişirir.
  */
 export declare const DEFAULT_HTML_CACHE_MAX_ENTRIES = 500;
+/**
+ * Edge taze penceresi bittikten sonra eski HTML'in sunulacağı süre (saniye).
+ * `cache().staleWhileRevalidate`. 0 ise `stale-while-revalidate` direktifi
+ * basılmaz. Süreç içi HTML cache'in stale penceresinden bağımsızdır.
+ */
+export declare const DEFAULT_STALE_WHILE_REVALIDATE = 60;
 /** `cache().maxEntries` için sert tavan. Üstü uyarıyla bu değere çekilir. */
 export declare const HTML_CACHE_MAX_ENTRIES_CEILING = 800;
 /**
@@ -139,6 +145,17 @@ export declare const HTML_CACHE_MAX_ENTRIES_CEILING = 800;
  * saklanmaz, yanıt yine gider.
  */
 export declare const HTML_CACHE_BYTE_BUDGET: number;
+/**
+ * Süreç içi veri önbelleğinin JSON bayt tavanı (64 MB). Sayı tavanı
+ * şişman gövdeleri tutmaz; config yükseltemez. Tek değer bütçeden büyükse
+ * saklanmaz, çağıran sonucu yine alır.
+ */
+export declare const DATA_CACHE_BYTE_BUDGET: number;
+/**
+ * Uzak görsel disk önbelleğinin tavanı (256 MB). `.jskelet/image-cache/`
+ * bu boyutu aşınca en eski dosya düşer. Config yükseltemez.
+ */
+export declare const IMAGE_CACHE_BYTE_BUDGET: number;
 /** `cache().data.maxEntries` için sert tavan. Uzun kuyruk burada durur, HTML'de değil. */
 export declare const DATA_CACHE_MAX_ENTRIES_CEILING = 20000;
 /**
@@ -262,7 +279,10 @@ export declare const DEFAULT_LOGS: {
         enabled: boolean;
         /** Proje köküne göre relative. */
         dir: string;
-        /** Yalnızca günlük rotasyon. */
+        /**
+         * Artık kullanılmıyor. Parçalar en fazla 5 dakika durur; alan çözülen
+         * config'te durur ki eski okuyucular kırılmasın.
+         */
         rotate: "daily";
     };
     s3: {

package/types/config/index.d.ts

@@ -45,11 +45,19 @@ export type LogsConfig = {
      * Sink'lere giden kayıt türleri.
      */
     kinds: LogKind[];
+    /**
+     *   `rotate` durur; dosya parçaları en fazla 5 dakika tutulur.
+     */
     file: {
         enabled: boolean;
         dir: string;
         rotate: "daily";
     };
+    /**
+     *   Mühürlenen zstd parçasını uygulamanın seçtiği yere aktarır. Hata
+     *   siteyi düşürmez.
+     */
+    drainLog: import('../server/logs/file-sink.js').DrainLog | null;
     s3: {
         enabled: boolean;
         bucket: string | null;
@@ -116,6 +124,12 @@ export type ResolvedConfig = {
      * HTML önbelleğinin girdi sınırı.
      */
     htmlMaxEntries: number;
+    /**
+     * Edge taze penceresi bittikten sonra
+     * eski HTML'in sunulacağı süre (saniye). 0 ise direktif basılmaz. Süreç içi
+     * HTML cache'in stale penceresinden bağımsızdır.
+     */
+    staleWhileRevalidate: number;
     /**
      * Upstream veri önbelleği ayarları.
      */

package/types/server/cache-blob.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Küçük gövde düz `string` döner (çağıran senkron yazabilsin). Büyük gövde
+ * brotli bitince çözülen bir Promise.
+ *
+ * @param {unknown} value
+ * @returns {string | Buffer | Promise<string | Buffer> | null}
+ */
+export declare function encodeCacheValue(value: unknown): string | Buffer | Promise<string | Buffer> | null;
+/**
+ * @param {Buffer | string} raw
+ * @returns {unknown}
+ */
+export declare function decodeCacheValue(raw: Buffer | string): unknown;

package/types/server/cache-control.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Tarayıcıya `max-age=0`, edge'e `CDN-Cache-Control`.
+ *
+ * `s-maxage` yazılmaz: Cloudflare `max-age=0` ile birlikte görünce nesneyi
+ * EXPIRED sayar. `must-revalidate`, `proxy-revalidate` ve `no-cache` aynı
+ * yanıtta stale penceresini keser; burada üretilmez. `s-maxage`'e dönen bir
+ * anahtar da yok — o mod aynı EXPIRED sonucunu geri getirir.
+ *
+ * Süreç içi HTML cache (`X-JSkelet-Cache: STALE`) ayrı katmandır; bu modül
+ * ona dokunmaz. Görsel optimizer kendi `max-age` + `stale-while-revalidate`
+ * yolunu kullanır.
+ */
+/**
+ * @param {number} maxAge Edge'in taze penceresi (saniye). HTML'de route TTL.
+ * @param {number} staleWhileRevalidate Taze pencere bitince eski kopyanın
+ *   sunulacağı süre. 0 ise direktif basılmaz.
+ * @returns {{ cacheControl: string, cdnCacheControl: string }}
+ */
+export declare function edgeCacheControl(maxAge: number, staleWhileRevalidate: number): {
+    cacheControl: string;
+    cdnCacheControl: string;
+};
+/**
+ * @param {import('express').Response} res
+ * @param {number} maxAge
+ * @param {number} staleWhileRevalidate
+ */
+export declare function setEdgeCacheHeaders(res: import('express').Response, maxAge: number, staleWhileRevalidate: number): void;

package/types/server/data-cache.d.ts

@@ -2,6 +2,7 @@ export type DataEntry = {
     value: unknown;
     expiresAt: number;
     staleUntil: number;
+    bytes: number;
 };
 /**
  * Süreç ömrü boyunca biriken sayaçlar.
@@ -90,6 +91,14 @@ export declare function clearDataCache(prefix?: string): number;
 export declare function dropDataCacheKey(key: string): boolean;
 /** @returns {number} */
 export declare function getDataCacheSize(): number;
+/**
+ * Bellek freninin bayt tavanını geçici olarak değiştirir. Testler LRU
+ * tahliyesini küçük bir değerle doğrular; `null` üretim tavanına döner.
+ *
+ * @param {number | null} bytes
+ * @returns {void}
+ */
+export declare function setDataCacheByteBudget(bytes: number | null): void;
 /**
  * Süreç başından beri biriken sayaçlar. `produced` kotaya yazılan tek sayıdır:
  * geri kalan her şey upstream'e hiç gitmemiş bir okuma.

package/types/server/disk-cache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @param {string | null} root Mutlak dizin, ya da config yoluna dönmek için `null`.
+ */
+export declare function setDiskCacheRootForTests(root: string | null): void;
+/**
+ * @param {"html" | "data"} kind
+ * @returns {boolean}
+ */
+export declare function diskShares(kind: "html" | "data"): boolean;
+/**
+ * @param {"html" | "data"} kind
+ * @param {string} key
+ * @returns {Promise<unknown | null>}
+ */
+export declare function diskGetJson(kind: "html" | "data", key: string): Promise<unknown | null>;
+/**
+ * Ateşle-unut. Dönüş değeri testler bekleyebilsin diye durur; istek yolu
+ * beklemez.
+ *
+ * @param {"html" | "data"} kind
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {Promise<void>}
+ */
+export declare function diskSetJson(kind: "html" | "data", key: string, value: unknown): Promise<void>;
+/**
+ * @param {"html" | "data"} kind
+ * @param {string[]} keys
+ */
+export declare function diskDrop(kind: "html" | "data", keys: string[]): void;
+/**
+ * @param {"html" | "data"} kind
+ * @param {(key: string) => boolean} [match] Verilmezse türün tamamı silinir.
+ * @returns {Promise<number>}
+ */
+export declare function diskDropMatching(kind: "html" | "data", match?: (key: string) => boolean): Promise<number>;

package/types/server/html-cache.d.ts

@@ -26,8 +26,8 @@
  * (L1) **birincil kalır**: `read()` senkron, sıkıştırılmış gövdeler girdiyle
  * birlikte ve tutarlılık makinesi (`tokens`, `purgedDeps`) tek proseste. Redis
  * yalnızca L1'de bulunmayan bir yol için render'ı atlatır ve invalidation'ı
- * diğer node'lara duyurur. Redis erişilemez olduğunda bu modül birebir eskisi
- * gibi çalışır.
+ * diğer node'lara duyurur. Redis yoksa aynı kayıt `.jskelet/cache/<buildId>/`
+ * altına yazılır; bu tek makinenin yeniden açılışını karşılar, kümeyi değil.
  */
 export type HtmlEntry = {
     html: string;
@@ -144,9 +144,10 @@ export declare function dropHtmlCacheKey(key: string): boolean;
  * açılmaz.
  *
  * @param {string} [onlyHost]
- * @returns {{ path: string, host: string }[]}
+ * @returns {{ key: string, path: string, host: string }[]}
  */
 export declare function takeInvalidatedTargets(onlyHost?: string): {
+    key: string;
     path: string;
     host: string;
 }[];
@@ -190,11 +191,33 @@ export declare function isHtmlCacheFresh(pathname: string, req?: {
     headers?: Record<string, unknown>;
     get?: (name: string) => string | undefined;
 }): boolean;
+/**
+ * Bu anahtarın girdisi hâlâ taze mi? Süre dolumu ısıtması anahtarı bildiği
+ * için yol taraması yapmaz. Soft-bayat (`expiresAt === 0`) taze sayılmaz:
+ * ziyaretçi arada yenilediyse yeni `expiresAt` taze döner ve HTTP atlanır.
+ *
+ * @param {string} key
+ * @returns {boolean}
+ */
+export declare function isHtmlCacheKeyFresh(key: string): boolean;
+/**
+ * Girdide en fazla bir sıkıştırılmış gövde durur. Yeni kodlama eskisinin
+ * yerini alır; ham HTML kalır. Bayt sayacı `noteHtmlCacheGrowth` ile işlenir.
+ *
+ * @param {Map<string, Buffer>} encoded
+ * @param {string} encoding
+ * @param {Buffer} buffer
+ * @returns {void}
+ */
+export declare function rememberHtmlEncoding(encoded: Map<string, Buffer>, encoding: string, buffer: Buffer): void;
 /**
  * Erken tazeleme penceresine girmiş (veya TTL'i dolmuş) trafiksiz girdileri
  * soft-bayatlatır ve ısıtma kuyruğuna alır. HTTP ısıtması producer'sız
  * çalıştığı için soft-bayat şart: taze HIT yenileme tetiklemez.
  *
+ * Tur başına en fazla `EARLY_SWEEP_MARK_BUDGET` girdi. Önce süresi en yakın
+ * dolacak olan; kota dolunca kalanlar bir sonraki tura kalır.
+ *
  * @returns {number} İşaretlenen girdi sayısı.
  */
 export declare function sweepEarlyExpiry(): number;

package/types/server/logs/file-sink.d.ts

@@ -1,17 +1,28 @@
+export type LogChunk = {
+    body: Buffer;
+    encoding: "zstd";
+    bytes: number;
+    lines: number;
+    at: number;
+};
 export type LogSink = {
     write: (entry: Record<string, unknown>) => Promise<void>;
     flush: () => Promise<void>;
     close: () => Promise<void>;
 };
+export type DrainLog = (chunk: LogChunk) => void | Promise<void>;
+/** Diskteki parçaların ömrü. Config yükseltemez. */
+export declare const FILE_LOG_RETENTION_MS: number;
 /**
- * @typedef {{ write: (entry: Record<string, unknown>) => Promise<void>,
- *   flush: () => Promise<void>, close: () => Promise<void> }} LogSink
- */
-/**
- * @param {{ root: string, dir: string }} options
+ * @param {{ root: string, dir: string, persist?: boolean,
+ *   retentionMs?: number, drainLog?: DrainLog | null }} options
+ *   `persist: false` diske yazmaz; yalnız `drainLog` çağrılır.
  * @returns {LogSink}
  */
 export declare function createFileSink(options: {
     root: string;
     dir: string;
+    persist?: boolean;
+    retentionMs?: number;
+    drainLog?: DrainLog | null;
 }): LogSink;

package/types/server/og-image.d.ts

@@ -94,6 +94,11 @@ export declare function buildOgSvg(options?: OgCardOptions & {
 export declare function ogImage(options?: OgImageOptions): Promise<OgImageResult>;
 /**
  * Express yanıtına OG görseli basar.
+ *
+ * Varsayılan edge penceresi 86400 / 604800'tür ve HTML TTL'ye bağlı değildir.
+ * `cacheControl` verilirse yalnızca `Cache-Control` yazılır;
+ * `CDN-Cache-Control` basılmaz.
+ *
  * @param {import('express').Response} res
  * @param {OgImageOptions} [options]
  * @returns {Promise<OgImageResult>}

package/types/server/redis.d.ts

@@ -56,7 +56,8 @@ export declare function cacheKey(kind: "html" | "data", key: string): string;
 export declare function redisGetJson(key: string): Promise<any | null>;
 /**
  * Ateşle-unut yazma. İsteğin yanıt yolunda beklenmez: HTML zaten L1'e
- * yazıldı, Redis kopyası yalnızca diğer node'lar için.
+ * yazıldı, Redis kopyası yalnızca diğer node'lar için. 1 KB ve üstü gövdeler
+ * brotli ile yazılır; okuma düz JSON'u da kabul eder.
  *
  * @param {string} key
  * @param {unknown} value