maven-proxy 1.2.1 → 1.3.1

package/README.md

@@ -256,6 +256,17 @@ curl.exe -k -sS -D - -o NUL -x http://127.0.0.1:8080 https://registry.npmjs.org/
 ### 8.4 Upstream Proxy Settings
 
 Environment variables:
+- CACHE_CLEANUP_ENABLED: enable automatic cache cleanup.
+- CACHE_CLEANUP_DAILY_AT: daily cleanup check time in local timezone (HH:mm), for example 03:00.
+- CACHE_CLEANUP_CHECK_MIN_INTERVAL: minimum interval between pressure checks (supports s/m/h/d), for example 10m.
+- CACHE_TOUCH_ON_HIT: update file mtime when cache hit returns successfully.
+- CACHE_TOUCH_MIN_INTERVAL: minimum interval between two touches for the same file (supports s/m/h/d), default 1d.
+- CACHE_RETENTION_START: initial retention window for cleanup rounds (supports s/m/h/d), default 10d.
+- CACHE_RETENTION_MIN: minimum retention window for cleanup rounds (supports s/m/h/d), default 1d.
+- CACHE_DISK_FREE_TRIGGER: trigger cleanup when disk free bytes are below this value (supports K/M/G/T), for example 20G.
+- CACHE_DISK_FREE_TARGET: stop cleanup when disk free bytes recover to this value (supports K/M/G/T), for example 25G.
+- CACHE_MAX_SIZE: optional cache-size trigger threshold (supports K/M/G/T).
+- CACHE_TARGET_SIZE: optional cache-size target to stop cleanup (supports K/M/G/T).
 - UPSTREAM_PROXY_URL: generic upstream proxy URL.
 - UPSTREAM_HTTP_PROXY_URL: upstream proxy for HTTP.
 - UPSTREAM_HTTPS_PROXY_URL: upstream proxy for HTTPS.
@@ -266,13 +277,18 @@ Environment variables:
 - MAVEN_REPO_DOMAINS: maven domains for ecosystem routing (wildcards supported).
 - HTTPS_MITM_DOMAINS: MITM domain list (includes registry.npmjs.org by default, wildcards supported).
 - DOWNLOAD_LOG_DIR: log directory.
-- LOG_RETENTION_DAYS: number of days to retain logs.
+- LOG_RETENTION: log retention duration (supports s/m/h/d), for example 7d.
 - LOG_TO_STDOUT: whether to also print runtime logs to stdout/stderr; startup logs are always printed.
 - LOG_CONNECT_EVENTS: whether to print verbose CONNECT/MITM handshake logs. Default false.
 - OUTBOUND_KEEP_ALIVE: enable outbound keep-alive connection pooling.
-- OUTBOUND_KEEP_ALIVE_SECONDS: keep-alive interval in seconds.
+- OUTBOUND_KEEP_ALIVE_INTERVAL: keep-alive interval (supports s/m/h/d), for example 1s.
 - OUTBOUND_MAX_SOCKETS: max outbound sockets per origin.
 - OUTBOUND_MAX_FREE_SOCKETS: max idle outbound sockets per origin.
+- MAVEN_AFFINITY_ENABLED: enable Maven affinity index.
+- MAVEN_AFFINITY_INDEX_DIR: Maven affinity index directory. Default data/index.
+- MAVEN_NEGATIVE_CACHE_TTL: negative cache TTL (supports s/m/h/d), for example 24h.
+- MAVEN_AFFINITY_FLUSH_INTERVAL: flush interval for affinity event log (supports s/m/h/d), for example 5s.
+- MAVEN_AFFINITY_EVENT_MAX_MB: max size threshold for affinity event log compaction in MB.
 - MAVEN_PROXY_CONFIG_MODE: development or user.
 - MAVEN_PROXY_CONFIG_FILE: explicit config file path.
 - EXISTING_TRUST_STORE_PATH: optional existing truststore path. If present, truststore init prefers it as source.
@@ -292,6 +308,17 @@ Priority:
 - `PROXY_PORT`: Proxy server port. Default `8080`.
 - `REPO_PORT`: Local repository server port. Default `8081`.
 - `CACHE_DIR`: Base cache directory. Default `data/cache`.
+- `CACHE_CLEANUP_ENABLED`: Enable automatic cache cleanup. Default `true`.
+- `CACHE_CLEANUP_DAILY_AT`: Daily cleanup check time in local timezone (`HH:mm`). Default `03:00`.
+- `CACHE_CLEANUP_CHECK_MIN_INTERVAL`: Minimum interval between pressure checks (supports `s/m/h/d`). Default `10m`.
+- `CACHE_TOUCH_ON_HIT`: Update file mtime when cache hit returns successfully. Default `true`.
+- `CACHE_TOUCH_MIN_INTERVAL`: Minimum interval between two touches for the same file (supports `s/m/h/d`). Default `1d`.
+- `CACHE_RETENTION_START`: Initial retention window for cleanup rounds (supports `s/m/h/d`). Default `10d`.
+- `CACHE_RETENTION_MIN`: Minimum retention window for cleanup rounds (supports `s/m/h/d`). Default `1d`.
+- `CACHE_DISK_FREE_TRIGGER`: Trigger cleanup when disk free bytes are below this value (supports `K/M/G/T`). Default `20G`.
+- `CACHE_DISK_FREE_TARGET`: Stop cleanup when disk free bytes recover to this value (supports `K/M/G/T`). Default `25G`.
+- `CACHE_MAX_SIZE`: Optional cache-size trigger threshold (supports `K/M/G/T`). Default empty (disabled).
+- `CACHE_TARGET_SIZE`: Optional cache-size target to stop cleanup (supports `K/M/G/T`). Default empty (disabled).
 - `REPO_FALLBACK_REPOS`: Comma-separated fallback repository URLs for cache misses.
 - `ENABLE_HTTPS_PROXY`: Enable HTTPS proxy handling (`true/false`).
 - `HTTPS_MITM_DOMAINS`: Comma-separated domains to apply MITM certificate issuance (wildcards supported).
@@ -301,15 +328,20 @@ Priority:
 - `MULTI_THREAD_DOMAINS`: Domains allowed to use multi-thread download (wildcards supported).
 - `MULTI_THREAD_COUNT`: Number of download threads for ranged downloads.
 - `MULTI_THREAD_MIN_SIZE_MB`: Minimum size threshold to trigger multi-thread download (MB).
-- `DOWNLOAD_TIMEOUT_SECONDS`: Upstream request timeout in seconds.
+- `DOWNLOAD_TIMEOUT`: Upstream request timeout (supports `s/m/h/d`). Default `60s`.
 - `DOWNLOAD_LOG_DIR`: Directory for unified app/error logs.
-- `LOG_RETENTION_DAYS`: Number of days to keep log files.
+- `LOG_RETENTION`: Log retention duration (supports `s/m/h/d`). Default `7d`.
 - `LOG_TO_STDOUT`: Whether to also print runtime logs to stdout/stderr. Startup logs are always printed. Default `true`.
 - `LOG_CONNECT_EVENTS`: Whether to print verbose CONNECT/MITM handshake logs. Default `false`.
 - `OUTBOUND_KEEP_ALIVE`: Enable outbound keep-alive connection pooling. Default `true`.
-- `OUTBOUND_KEEP_ALIVE_SECONDS`: Keep-alive interval in seconds. Default `1`.
+- `OUTBOUND_KEEP_ALIVE_INTERVAL`: Keep-alive interval (supports `s/m/h/d`). Default `1s`.
 - `OUTBOUND_MAX_SOCKETS`: Max outbound sockets per origin. Default `64`.
 - `OUTBOUND_MAX_FREE_SOCKETS`: Max idle outbound sockets per origin. Default `16`.
+- `MAVEN_AFFINITY_ENABLED`: Enable Maven affinity cache index. Default `true`.
+- `MAVEN_AFFINITY_INDEX_DIR`: Maven affinity index directory. Default `data/index`.
+- `MAVEN_NEGATIVE_CACHE_TTL`: Negative cache TTL (supports `s/m/h/d`). Default `24h`.
+- `MAVEN_AFFINITY_FLUSH_INTERVAL`: Flush interval for affinity event log (supports `s/m/h/d`). Default `5s`.
+- `MAVEN_AFFINITY_EVENT_MAX_MB`: Max size threshold for affinity event log compaction in MB. Default `8`.
 - `UPSTREAM_PROXY_URL`: Generic upstream proxy URL (fallback for HTTP/HTTPS).
 - `UPSTREAM_HTTP_PROXY_URL`: Upstream proxy URL for HTTP requests.
 - `UPSTREAM_HTTPS_PROXY_URL`: Upstream proxy URL for HTTPS requests.

package/bin/maven-proxy.js

@@ -140,52 +140,79 @@ function resolvePath(inputPath) {
 }
 
 function getDefaultConfigTemplate() {
-  return [
+  const lines = [
     "# Maven Proxy default user config",
+    "# Maven Proxy 用户模式默认配置",
     "# This file is loaded by default in user mode.",
     "",
-    "PROXY_PORT=8080",
-    "REPO_PORT=8081",
-    "CACHE_DIR=data/cache",
-    "REPO_FALLBACK_REPOS=https://repo1.maven.org/maven2,https://jitpack.io,https://plugins.gradle.org/m2,https://maven.google.com",
-    "ENABLE_HTTPS_PROXY=true",
-    "HTTPS_MITM_DOMAINS=repo1.maven.org,repo.maven.apache.org,registry.npmjs.org",
-    "HTTPS_PASSTHROUGH_FOR_UNMATCHED=false",
-    "NPM_REGISTRY_DOMAINS=registry.npmjs.org,registry.npmmirror.com,npm.pkg.github.com",
-    "MAVEN_REPO_DOMAINS=repo1.maven.org,repo.maven.apache.org,jitpack.io,plugins.gradle.org,maven.google.com",
-    "MULTI_THREAD_DOMAINS=repo1.maven.org",
-    "MULTI_THREAD_COUNT=8",
-    "MULTI_THREAD_MIN_SIZE_MB=1",
-    "DOWNLOAD_TIMEOUT_SECONDS=60",
-    "OUTBOUND_KEEP_ALIVE=true",
-    "OUTBOUND_KEEP_ALIVE_SECONDS=1",
-    "OUTBOUND_MAX_SOCKETS=64",
-    "OUTBOUND_MAX_FREE_SOCKETS=16",
-    "MAVEN_AFFINITY_ENABLED=true",
-    "MAVEN_AFFINITY_INDEX_DIR=.index",
-    "MAVEN_NEGATIVE_CACHE_TTL_HOURS=24",
-    "MAVEN_AFFINITY_FLUSH_INTERVAL_SECONDS=5",
-    "MAVEN_AFFINITY_EVENT_MAX_MB=8",
-    "DOWNLOAD_LOG_DIR=data/logs/downloads",
-    "LOG_RETENTION_DAYS=7",
-    "LOG_TO_STDOUT=false",
-    "UPSTREAM_PROXY_URL=",
-    "UPSTREAM_HTTP_PROXY_URL=",
-    "UPSTREAM_HTTPS_PROXY_URL=",
-    "UPSTREAM_NO_PROXY=127.0.0.1,localhost",
-    "UPSTREAM_IGNORE_DOMAINS=",
-    "CERT_DIR=data/certs",
-    "ROOT_CERT_PATH=data/certs/root-ca.crt",
-    "ROOT_KEY_PATH=data/certs/root-ca.key.pem",
-    "LEAF_CERT_DIR=data/certs/leaf",
-    "TRUST_STORE_PATH=data/certs/proxy-truststore.jks",
-    "TRUST_STORE_ALIAS=maven-proxy-root-ca",
-    "TRUST_STORE_PASSWORD=changeit",
-    "EXISTING_TRUST_STORE_PATH=",
-    "EXISTING_TRUST_STORE_PASSWORD=",
-    "JAVA_HOME=",
-    "",
-  ].join("\n");
+  ];
+
+  const appendEntry = (key, value, zhComment, enComment) => {
+    lines.push(`# 中文: ${zhComment}`);
+    lines.push(`# English: ${enComment}`);
+    lines.push(`${key}=${value}`);
+    lines.push("");
+  };
+
+  appendEntry("PROXY_PORT", "8080", "代理服务端口，默认 8080。", "Proxy service port. Default: 8080.");
+  appendEntry("REPO_PORT", "8081", "本地仓库服务端口，默认 8081。", "Local repository service port. Default: 8081.");
+  appendEntry("CACHE_DIR", "data/cache", "缓存根目录，默认 data/cache。", "Cache root directory. Default: data/cache.");
+  appendEntry("CACHE_CLEANUP_ENABLED", "true", "是否启用自动缓存清理，默认 true。", "Enable automatic cache cleanup. Default: true.");
+  appendEntry("CACHE_CLEANUP_DAILY_AT", "03:00", "每日固定检查时间（本地时区，HH:mm），默认 03:00。", "Fixed daily check time in local timezone (HH:mm). Default: 03:00.");
+  appendEntry("CACHE_CLEANUP_CHECK_MIN_INTERVAL", "10m", "压力检测最小间隔（支持 s/m/h/d），默认 10m。", "Minimum interval for pressure checks (supports s/m/h/d). Default: 10m.");
+  appendEntry("CACHE_TOUCH_ON_HIT", "true", "缓存命中返回时是否更新文件 mtime，默认 true。", "Update file mtime when serving cache hit. Default: true.");
+  appendEntry("CACHE_TOUCH_MIN_INTERVAL", "1d", "同一文件两次 touch 最小间隔（支持 s/m/h/d），默认 1d。", "Minimum interval between touches for the same file (supports s/m/h/d). Default: 1d.");
+  appendEntry("CACHE_RETENTION_START", "10d", "清理轮次初始保留窗口（支持 s/m/h/d），默认 10d。", "Initial retention window for cleanup cycle (supports s/m/h/d). Default: 10d.");
+  appendEntry("CACHE_RETENTION_MIN", "1d", "清理轮次最小保留窗口（支持 s/m/h/d），默认 1d。", "Minimum retention window for cleanup cycle (supports s/m/h/d). Default: 1d.");
+  appendEntry("CACHE_DISK_FREE_TRIGGER", "20G", "磁盘剩余空间低于该值触发清理（支持 K/M/G/T），默认 20G。", "Trigger cleanup when free disk space is below this value (supports K/M/G/T). Default: 20G.");
+  appendEntry("CACHE_DISK_FREE_TARGET", "25G", "磁盘剩余空间恢复到该值可停止清理（支持 K/M/G/T），默认 25G。", "Stop cleanup when free disk space recovers to this value (supports K/M/G/T). Default: 25G.");
+  appendEntry("CACHE_MAX_SIZE", "", "可选：缓存总大小触发阈值（支持 K/M/G/T），默认空（禁用）。", "Optional: cache total size trigger threshold (supports K/M/G/T). Default: empty (disabled).");
+  appendEntry("CACHE_TARGET_SIZE", "", "可选：缓存总大小回落目标（支持 K/M/G/T），默认空（禁用）。", "Optional: cache size recovery target (supports K/M/G/T). Default: empty (disabled).");
+  appendEntry(
+    "REPO_FALLBACK_REPOS",
+    "https://repo1.maven.org/maven2,https://jitpack.io,https://plugins.gradle.org/m2,https://dl.google.com",
+    "缓存未命中时回源仓库列表（逗号分隔）。",
+    "Fallback repository list when cache misses (comma-separated).",
+  );
+  appendEntry("ENABLE_HTTPS_PROXY", "true", "是否启用 HTTPS 代理处理（true/false），默认 true。", "Enable HTTPS proxy handling (true/false). Default: true.");
+  appendEntry("HTTPS_MITM_DOMAINS", "repo1.maven.org,repo.maven.apache.org,registry.npmjs.org", "执行 MITM 证书签发的域名列表（逗号分隔，支持通配符）。", "Domains for MITM certificate issuance (comma-separated, wildcard supported).");
+  appendEntry("HTTPS_PASSTHROUGH_FOR_UNMATCHED", "false", "未命中 MITM 域名时是否允许隧道透传，默认 false。", "Allow tunnel passthrough for unmatched MITM domains. Default: false.");
+  appendEntry("NPM_REGISTRY_DOMAINS", "registry.npmjs.org,registry.npmmirror.com,npm.pkg.github.com", "识别为 npm 生态并分流缓存的域名列表（支持通配符）。", "Domains recognized as npm ecosystem for cache routing (wildcard supported).");
+  appendEntry("MAVEN_REPO_DOMAINS", "repo1.maven.org,repo.maven.apache.org,jitpack.io,plugins.gradle.org,dl.google.com", "识别为 Maven 生态并分流缓存的域名列表（支持通配符）。", "Domains recognized as Maven ecosystem for cache routing (wildcard supported).");
+  appendEntry("MULTI_THREAD_DOMAINS", "repo1.maven.org", "启用多线程下载的域名列表（支持通配符）。", "Domains that enable multi-thread download (wildcard supported).");
+  appendEntry("MULTI_THREAD_COUNT", "8", "多线程下载线程数，默认 8。", "Thread count for multi-thread download. Default: 8.");
+  appendEntry("MULTI_THREAD_MIN_SIZE_MB", "1", "触发多线程下载的最小文件大小阈值（MB），默认 1。", "Minimum file size threshold in MB to trigger multi-thread download. Default: 1.");
+  appendEntry("DOWNLOAD_TIMEOUT", "60s", "上游请求超时时间（支持 s/m/h/d），默认 60s。", "Upstream request timeout (supports s/m/h/d). Default: 60s.");
+  appendEntry("DOWNLOAD_LOG_DIR", "data/logs/downloads", "统一主日志与错误日志目录。", "Unified main and error log directory.");
+  appendEntry("LOG_RETENTION", "7d", "日志保留时长（支持 s/m/h/d），默认 7d。", "Log retention duration (supports s/m/h/d). Default: 7d.");
+  appendEntry("LOG_TO_STDOUT", "false", "是否输出运行期日志到命令行，默认 false。", "Output runtime logs to stdout. Default: false.");
+  appendEntry("LOG_CONNECT_EVENTS", "false", "是否输出详细 CONNECT/MITM 握手日志，默认 false。", "Output detailed CONNECT/MITM handshake logs. Default: false.");
+  appendEntry("OUTBOUND_KEEP_ALIVE", "true", "是否启用出站 keep-alive 连接复用池，默认 true。", "Enable outbound keep-alive connection pool. Default: true.");
+  appendEntry("OUTBOUND_KEEP_ALIVE_INTERVAL", "1s", "keep-alive 间隔（支持 s/m/h/d），默认 1s。", "Keep-alive interval (supports s/m/h/d). Default: 1s.");
+  appendEntry("OUTBOUND_MAX_SOCKETS", "64", "每个源站最大出站连接数，默认 64。", "Maximum outbound sockets per upstream host. Default: 64.");
+  appendEntry("OUTBOUND_MAX_FREE_SOCKETS", "16", "每个源站可保留空闲连接上限，默认 16。", "Maximum free outbound sockets kept per upstream host. Default: 16.");
+  appendEntry("MAVEN_AFFINITY_ENABLED", "true", "是否启用 Maven affinity 缓存索引，默认 true。", "Enable Maven affinity index. Default: true.");
+  appendEntry("MAVEN_AFFINITY_INDEX_DIR", "data/index", "Maven affinity 索引目录，默认 data/index。", "Maven affinity index directory. Default: data/index.");
+  appendEntry("MAVEN_NEGATIVE_CACHE_TTL", "24h", "负缓存 TTL（支持 s/m/h/d），默认 24h。", "Negative cache TTL (supports s/m/h/d). Default: 24h.");
+  appendEntry("MAVEN_AFFINITY_FLUSH_INTERVAL", "5s", "affinity 事件日志 flush 周期（支持 s/m/h/d），默认 5s。", "Affinity event log flush interval (supports s/m/h/d). Default: 5s.");
+  appendEntry("MAVEN_AFFINITY_EVENT_MAX_MB", "8", "affinity 事件日志压缩阈值（MB），默认 8。", "Affinity event log compaction threshold in MB. Default: 8.");
+  appendEntry("UPSTREAM_PROXY_URL", "", "通用上级代理地址（HTTP/HTTPS 兜底）。", "Generic upstream proxy URL fallback for HTTP/HTTPS.");
+  appendEntry("UPSTREAM_HTTP_PROXY_URL", "", "HTTP 请求使用的上级代理地址。", "Upstream proxy URL for HTTP requests.");
+  appendEntry("UPSTREAM_HTTPS_PROXY_URL", "", "HTTPS 请求使用的上级代理地址。", "Upstream proxy URL for HTTPS requests.");
+  appendEntry("UPSTREAM_NO_PROXY", "127.0.0.1,localhost", "不走上级代理的域名列表（逗号分隔，支持通配符，* 表示全部直连）。", "Domains that bypass upstream proxy (comma-separated, wildcard supported, * means direct for all).");
+  appendEntry("UPSTREAM_IGNORE_DOMAINS", "", "额外忽略上级代理的域名列表（支持通配符）。", "Additional domains ignored by upstream proxy (wildcard supported).");
+  appendEntry("CERT_DIR", "data/certs", "证书根目录，默认 data/certs。", "Certificate root directory. Default: data/certs.");
+  appendEntry("ROOT_CERT_PATH", "data/certs/root-ca.crt", "Root CA 证书路径。", "Root CA certificate path.");
+  appendEntry("ROOT_KEY_PATH", "data/certs/root-ca.key.pem", "Root CA 私钥路径。", "Root CA private key path.");
+  appendEntry("LEAF_CERT_DIR", "data/certs/leaf", "站点叶子证书目录。", "Leaf certificate directory.");
+  appendEntry("TRUST_STORE_PATH", "data/certs/proxy-truststore.jks", "Java trust store 文件路径。", "Java trust store file path.");
+  appendEntry("TRUST_STORE_ALIAS", "maven-proxy-root-ca", "导入 Root CA 到 trust store 时使用的别名。", "Alias used to import Root CA into trust store.");
+  appendEntry("TRUST_STORE_PASSWORD", "changeit", "trust store 密码。", "Trust store password.");
+  appendEntry("EXISTING_TRUST_STORE_PATH", "", "已有 truststore 路径（可选），初始化时可作为源。", "Existing truststore path (optional), used as source during init.");
+  appendEntry("EXISTING_TRUST_STORE_PASSWORD", "", "已有 truststore 密码（可选），用于读取 EXISTING_TRUST_STORE_PATH。", "Existing truststore password (optional), used to read EXISTING_TRUST_STORE_PATH.");
+  appendEntry("JAVA_HOME", "", "Java 安装路径；为空或无效时会自动探测。", "Java installation path; auto-detected when empty or invalid.");
+
+  return `${lines.join("\n").trimEnd()}\n`;
 }
 
 async function initConfigFile(configFile, force = false) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maven-proxy",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "Maven proxy with cache, HTTPS MITM for selected domains, and local repo publishing",
   "main": "src/index.js",
   "bin": {
@@ -19,6 +19,7 @@
     "cli:start": "node bin/maven-proxy.js start --mode development",
     "cli:stop": "node bin/maven-proxy.js stop",
     "cli:doctor": "node bin/maven-proxy.js doctor --mode development",
+    "cli:doctor:user": "node bin/maven-proxy.js doctor --mode user",
     "cli:truststore:print": "node bin/maven-proxy.js truststore print --mode development",
     "cli:truststore:init": "node bin/maven-proxy.js truststore init --mode development",
     "cli:truststore:merge": "node bin/maven-proxy.js truststore merge --mode development",

package/src/cache/cache-cleanup-manager.js

@@ -0,0 +1,416 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const SECOND_MS = 1000;
+const MINUTE_MS = 60 * SECOND_MS;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+
+function toBool(value, fallback) {
+  if (value == null || value === "") {
+    return fallback;
+  }
+
+  return ["1", "true", "yes", "on"].includes(String(value).toLowerCase());
+}
+
+function parseDurationToMs(raw, fallbackMs) {
+  const text = String(raw || "").trim();
+  if (!text) {
+    return fallbackMs;
+  }
+
+  const match = text.match(/^(\d+)([smhd])$/i);
+  if (!match) {
+    return fallbackMs;
+  }
+
+  const value = Number.parseInt(match[1], 10);
+  const unit = match[2].toLowerCase();
+  if (!Number.isFinite(value) || value < 0) {
+    return fallbackMs;
+  }
+
+  if (unit === "s") {
+    return value * SECOND_MS;
+  }
+  if (unit === "m") {
+    return value * MINUTE_MS;
+  }
+  if (unit === "h") {
+    return value * HOUR_MS;
+  }
+
+  return value * DAY_MS;
+}
+
+function parseSizeToBytes(raw, fallbackBytes = 0) {
+  const text = String(raw || "").trim();
+  if (!text) {
+    return fallbackBytes;
+  }
+
+  const match = text.match(/^(\d+)([KMGT]?)$/i);
+  if (!match) {
+    return fallbackBytes;
+  }
+
+  const value = Number.parseInt(match[1], 10);
+  if (!Number.isFinite(value) || value < 0) {
+    return fallbackBytes;
+  }
+
+  const unit = String(match[2] || "").toUpperCase();
+  const unitPow = {
+    "": 0,
+    K: 1,
+    M: 2,
+    G: 3,
+    T: 4,
+  }[unit];
+
+  if (unitPow == null) {
+    return fallbackBytes;
+  }
+
+  return value * (1024 ** unitPow);
+}
+
+function parseDailyAt(text, fallback = { hour: 3, minute: 0 }) {
+  const raw = String(text || "").trim();
+  const match = raw.match(/^(\d{1,2}):(\d{2})$/);
+  if (!match) {
+    return fallback;
+  }
+
+  const hour = Number.parseInt(match[1], 10);
+  const minute = Number.parseInt(match[2], 10);
+
+  if (hour < 0 || hour > 23 || minute < 0 || minute > 59) {
+    return fallback;
+  }
+
+  return { hour, minute };
+}
+
+async function statIfFile(filePath) {
+  try {
+    const stats = await fs.promises.stat(filePath);
+    return stats.isFile() ? stats : null;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function getDiskFreeBytes(targetDir) {
+  if (typeof fs.promises.statfs !== "function") {
+    return Number.POSITIVE_INFINITY;
+  }
+
+  const info = await fs.promises.statfs(targetDir);
+  return Number(info.bavail || 0) * Number(info.bsize || 0);
+}
+
+async function walkFiles(dirPath, onFile) {
+  const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+
+    if (entry.isDirectory()) {
+      await walkFiles(fullPath, onFile);
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    await onFile(fullPath);
+  }
+}
+
+async function getDirSizeBytes(dirPath) {
+  let total = 0;
+
+  try {
+    await walkFiles(dirPath, async (filePath) => {
+      const stats = await statIfFile(filePath);
+      if (stats) {
+        total += stats.size;
+      }
+    });
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  return total;
+}
+
+function formatBytes(bytes) {
+  const value = Number(bytes || 0);
+  if (!Number.isFinite(value) || value < 0) {
+    return "0B";
+  }
+
+  if (value >= 1024 ** 4) {
+    return `${(value / (1024 ** 4)).toFixed(2)}TB`;
+  }
+  if (value >= 1024 ** 3) {
+    return `${(value / (1024 ** 3)).toFixed(2)}GB`;
+  }
+  if (value >= 1024 ** 2) {
+    return `${(value / (1024 ** 2)).toFixed(2)}MB`;
+  }
+  if (value >= 1024) {
+    return `${(value / 1024).toFixed(2)}KB`;
+  }
+
+  return `${Math.floor(value)}B`;
+}
+
+export class CacheCleanupManager {
+  constructor(config) {
+    this.config = config;
+    this.enabled = toBool(config.cacheCleanupEnabled, true);
+    this.touchOnHit = toBool(config.cacheTouchOnHit, true);
+    this.touchMinIntervalMs = Math.max(0, parseDurationToMs(config.cacheTouchMinInterval, DAY_MS));
+    this.retentionStartDays = Math.max(1, Math.floor(parseDurationToMs(config.cacheRetentionStart, 10 * DAY_MS) / DAY_MS));
+    this.retentionMinDays = Math.max(1, Math.floor(parseDurationToMs(config.cacheRetentionMin, DAY_MS) / DAY_MS));
+    this.diskFreeTriggerBytes = Math.max(0, parseSizeToBytes(config.cacheDiskFreeTrigger, 20 * 1024 ** 3));
+    this.diskFreeTargetBytes = Math.max(
+      this.diskFreeTriggerBytes,
+      parseSizeToBytes(config.cacheDiskFreeTarget, 25 * 1024 ** 3),
+    );
+    this.cacheMaxSizeBytes = Math.max(0, parseSizeToBytes(config.cacheMaxSize, 0));
+    this.cacheTargetSizeBytes = Math.max(
+      0,
+      parseSizeToBytes(config.cacheTargetSize, this.cacheMaxSizeBytes || 0),
+    );
+    this.checkMinIntervalMs = Math.max(MINUTE_MS, parseDurationToMs(config.cacheCleanupCheckMinInterval, 10 * MINUTE_MS));
+    this.dailyAt = parseDailyAt(config.cacheCleanupDailyAt, { hour: 3, minute: 0 });
+
+    this.lastTouchAt = new Map();
+    this.lastPressureCheckAt = 0;
+    this.cleanupRunning = false;
+    this.dailyTimer = null;
+  }
+
+  async init() {
+    if (!this.enabled) {
+      return;
+    }
+
+    this.#scheduleDailyCheck();
+  }
+
+  async destroy() {
+    if (this.dailyTimer) {
+      clearTimeout(this.dailyTimer);
+      this.dailyTimer = null;
+    }
+  }
+
+  touchFileOnHit(filePath) {
+    if (!this.enabled || !this.touchOnHit || !filePath) {
+      return;
+    }
+
+    const now = Date.now();
+    const last = this.lastTouchAt.get(filePath) || 0;
+    if (now - last < this.touchMinIntervalMs) {
+      return;
+    }
+
+    this.lastTouchAt.set(filePath, now);
+
+    fs.promises.utimes(filePath, new Date(now), new Date(now)).catch((error) => {
+      if (error.code !== "ENOENT") {
+        console.warn(`[cache-cleanup] touch failed path=${filePath} message=${error.message}`);
+      }
+    });
+  }
+
+  async checkAndCleanupIfNeeded(reason = "manual", force = false) {
+    if (!this.enabled) {
+      return { triggered: false, reason: "disabled" };
+    }
+
+    const now = Date.now();
+    if (!force && now - this.lastPressureCheckAt < this.checkMinIntervalMs) {
+      return { triggered: false, reason: "throttled" };
+    }
+    this.lastPressureCheckAt = now;
+
+    const metrics = await this.#collectMetrics();
+    const overLimit = this.#isOverLimit(metrics);
+
+    if (!overLimit) {
+      return {
+        triggered: false,
+        reason: "below-limit",
+        metrics,
+      };
+    }
+
+    return this.#runCleanup(reason, metrics);
+  }
+
+  async #runCleanup(reason, beforeMetrics) {
+    if (this.cleanupRunning) {
+      return { triggered: false, reason: "already-running" };
+    }
+
+    this.cleanupRunning = true;
+
+    try {
+      console.warn(
+        `[cache-cleanup] start reason=${reason} free=${formatBytes(beforeMetrics.diskFreeBytes)} cache=${formatBytes(beforeMetrics.cacheSizeBytes)}`,
+      );
+
+      const rounds = [];
+      const startDay = Math.max(this.retentionStartDays, this.retentionMinDays);
+      const endDay = this.retentionMinDays;
+
+      for (let day = startDay; day >= endDay; day -= 1) {
+        const cutoffMs = Date.now() - (day * DAY_MS);
+        const result = await this.#deleteOlderThan(cutoffMs);
+        const metrics = await this.#collectMetrics();
+
+        rounds.push({
+          day,
+          deletedFiles: result.deletedFiles,
+          releasedBytes: result.releasedBytes,
+          diskFreeBytes: metrics.diskFreeBytes,
+          cacheSizeBytes: metrics.cacheSizeBytes,
+        });
+
+        console.warn(
+          `[cache-cleanup] round day=${day} deleted=${result.deletedFiles} released=${formatBytes(result.releasedBytes)} free=${formatBytes(metrics.diskFreeBytes)} cache=${formatBytes(metrics.cacheSizeBytes)}`,
+        );
+
+        if (this.#meetsTarget(metrics)) {
+          console.warn(`[cache-cleanup] success reason=${reason} stop-day=${day}`);
+          return {
+            triggered: true,
+            success: true,
+            stopDay: day,
+            before: beforeMetrics,
+            after: metrics,
+            rounds,
+          };
+        }
+      }
+
+      const afterMetrics = await this.#collectMetrics();
+      console.error(
+        `[cache-cleanup] warn cannot meet target at min-day=${this.retentionMinDays} free=${formatBytes(afterMetrics.diskFreeBytes)} cache=${formatBytes(afterMetrics.cacheSizeBytes)}`,
+      );
+
+      return {
+        triggered: true,
+        success: false,
+        stopDay: this.retentionMinDays,
+        before: beforeMetrics,
+        after: afterMetrics,
+        rounds,
+      };
+    } finally {
+      this.cleanupRunning = false;
+    }
+  }
+
+  async #deleteOlderThan(cutoffMs) {
+    let deletedFiles = 0;
+    let releasedBytes = 0;
+
+    try {
+      await walkFiles(this.config.cacheDir, async (filePath) => {
+        const stats = await statIfFile(filePath);
+        if (!stats) {
+          return;
+        }
+
+        if (stats.mtimeMs >= cutoffMs) {
+          return;
+        }
+
+        try {
+          await fs.promises.unlink(filePath);
+          deletedFiles += 1;
+          releasedBytes += stats.size;
+          this.lastTouchAt.delete(filePath);
+        } catch (error) {
+          if (error.code !== "ENOENT") {
+            console.warn(`[cache-cleanup] delete failed path=${filePath} message=${error.message}`);
+          }
+        }
+      });
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+
+    return { deletedFiles, releasedBytes };
+  }
+
+  async #collectMetrics() {
+    const [diskFreeBytes, cacheSizeBytes] = await Promise.all([
+      getDiskFreeBytes(this.config.cacheDir),
+      getDirSizeBytes(this.config.cacheDir),
+    ]);
+
+    return { diskFreeBytes, cacheSizeBytes };
+  }
+
+  #isOverLimit(metrics) {
+    const diskLow = this.diskFreeTriggerBytes > 0 && metrics.diskFreeBytes <= this.diskFreeTriggerBytes;
+    const cacheOver = this.cacheMaxSizeBytes > 0 && metrics.cacheSizeBytes >= this.cacheMaxSizeBytes;
+    return diskLow || cacheOver;
+  }
+
+  #meetsTarget(metrics) {
+    const diskOk =
+      this.diskFreeTriggerBytes <= 0 ||
+      metrics.diskFreeBytes >= this.diskFreeTargetBytes;
+
+    const cacheTarget = this.cacheTargetSizeBytes > 0 ? this.cacheTargetSizeBytes : this.cacheMaxSizeBytes;
+    const cacheOk =
+      this.cacheMaxSizeBytes <= 0 ||
+      (cacheTarget > 0 && metrics.cacheSizeBytes <= cacheTarget);
+
+    return diskOk && cacheOk;
+  }
+
+  #scheduleDailyCheck() {
+    const now = new Date();
+    const next = new Date(now);
+    next.setHours(this.dailyAt.hour, this.dailyAt.minute, 0, 0);
+
+    if (next.getTime() <= now.getTime()) {
+      next.setDate(next.getDate() + 1);
+    }
+
+    const delay = Math.max(1000, next.getTime() - now.getTime());
+
+    this.dailyTimer = setTimeout(() => {
+      this.checkAndCleanupIfNeeded("daily-check", true)
+        .catch((error) => {
+          console.error(`[cache-cleanup] daily check failed: ${error.message}`);
+        })
+        .finally(() => {
+          this.#scheduleDailyCheck();
+        });
+    }, delay);
+
+    if (typeof this.dailyTimer.unref === "function") {
+      this.dailyTimer.unref();
+    }
+  }
+}

package/src/config/config.js

@@ -99,6 +99,38 @@ function toInt(value, defaultValue) {
   return Number.isFinite(parsed) ? parsed : defaultValue;
 }
 
+function parseDurationToMs(value, fallbackMs) {
+  const text = String(value || "").trim();
+  if (!text) {
+    return fallbackMs;
+  }
+
+  const match = text.match(/^(\d+)([smhd])$/i);
+  if (!match) {
+    return fallbackMs;
+  }
+
+  const amount = Number.parseInt(match[1], 10);
+  const unit = String(match[2] || "").toLowerCase();
+  if (!Number.isFinite(amount) || amount < 0) {
+    return fallbackMs;
+  }
+
+  if (unit === "s") {
+    return amount * 1000;
+  }
+
+  if (unit === "m") {
+    return amount * 60 * 1000;
+  }
+
+  if (unit === "h") {
+    return amount * 60 * 60 * 1000;
+  }
+
+  return amount * 24 * 60 * 60 * 1000;
+}
+
 function toList(value, defaultValue = []) {
   if (!value) {
     return defaultValue;
@@ -161,7 +193,7 @@ const defaultRepoFallbackRepos = [
   "https://repo1.maven.org/maven2",
   "https://jitpack.io",
   "https://plugins.gradle.org/m2",
-  "https://maven.google.com",
+  "https://dl.google.com",
 ];
 
 const repoFallbackRepos = normalizeRepoList(
@@ -174,17 +206,24 @@ const defaultMavenRepoDomains = [
   "repo.maven.apache.org",
   "jitpack.io",
   "plugins.gradle.org",
-  "maven.google.com",
+  "dl.google.com",
   ...extractHostsFromUrls(repoFallbackRepos),
 ];
 
 const cacheDir = path.resolve(configBaseDir, process.env.CACHE_DIR || "data/cache");
 
 const multiThreadMinSizeBytes = Math.max(0, toInt(process.env.MULTI_THREAD_MIN_SIZE_MB, 1)) * 1024 * 1024;
-const downloadTimeoutMs = Math.max(1, toInt(process.env.DOWNLOAD_TIMEOUT_SECONDS, 60)) * 1000;
-const outboundKeepAliveMsecs = Math.max(1, toInt(process.env.OUTBOUND_KEEP_ALIVE_SECONDS, 1)) * 1000;
-const mavenNegativeCacheTtlMs = Math.max(1, toInt(process.env.MAVEN_NEGATIVE_CACHE_TTL_HOURS, 24)) * 60 * 60 * 1000;
-const mavenAffinityFlushIntervalMs = Math.max(1, toInt(process.env.MAVEN_AFFINITY_FLUSH_INTERVAL_SECONDS, 5)) * 1000;
+const downloadTimeout = process.env.DOWNLOAD_TIMEOUT || "60s";
+const outboundKeepAliveInterval = process.env.OUTBOUND_KEEP_ALIVE_INTERVAL || "1s";
+const mavenNegativeCacheTtl = process.env.MAVEN_NEGATIVE_CACHE_TTL || "24h";
+const mavenAffinityFlushInterval = process.env.MAVEN_AFFINITY_FLUSH_INTERVAL || "5s";
+const logRetention = process.env.LOG_RETENTION || "7d";
+
+const downloadTimeoutMs = Math.max(1, parseDurationToMs(downloadTimeout, 60 * 1000));
+const outboundKeepAliveMsecs = Math.max(1, parseDurationToMs(outboundKeepAliveInterval, 1000));
+const mavenNegativeCacheTtlMs = Math.max(1, parseDurationToMs(mavenNegativeCacheTtl, 24 * 60 * 60 * 1000));
+const mavenAffinityFlushIntervalMs = Math.max(1, parseDurationToMs(mavenAffinityFlushInterval, 5 * 1000));
+const logRetentionDays = Math.max(1, Math.ceil(parseDurationToMs(logRetention, 7 * 24 * 60 * 60 * 1000) / (24 * 60 * 60 * 1000)));
 const mavenAffinityEventMaxBytes = Math.max(1, toInt(process.env.MAVEN_AFFINITY_EVENT_MAX_MB, 8)) * 1024 * 1024;
 
 export const config = {
@@ -205,18 +244,34 @@ export const config = {
   multiThreadDomains: toList(process.env.MULTI_THREAD_DOMAINS, ["repo1.maven.org"]),
   multiThreadCount: Math.max(1, toInt(process.env.MULTI_THREAD_COUNT, 4)),
   multiThreadMinSizeBytes,
+  downloadTimeout,
   downloadTimeoutMs,
   outboundKeepAlive: toBool(process.env.OUTBOUND_KEEP_ALIVE, true),
+  outboundKeepAliveInterval,
   outboundKeepAliveMsecs,
   outboundMaxSockets: Math.max(1, toInt(process.env.OUTBOUND_MAX_SOCKETS, 64)),
   outboundMaxFreeSockets: Math.max(1, toInt(process.env.OUTBOUND_MAX_FREE_SOCKETS, 16)),
   mavenAffinityEnabled: toBool(process.env.MAVEN_AFFINITY_ENABLED, true),
-  mavenAffinityIndexDir: path.resolve(cacheDir, process.env.MAVEN_AFFINITY_INDEX_DIR || ".index"),
+  mavenAffinityIndexDir: path.resolve(configBaseDir, process.env.MAVEN_AFFINITY_INDEX_DIR || "data/index"),
+  mavenNegativeCacheTtl,
   mavenNegativeCacheTtlMs,
+  mavenAffinityFlushInterval,
   mavenAffinityFlushIntervalMs,
   mavenAffinityEventMaxBytes,
+  cacheCleanupEnabled: toBool(process.env.CACHE_CLEANUP_ENABLED, true),
+  cacheCleanupDailyAt: process.env.CACHE_CLEANUP_DAILY_AT || "03:00",
+  cacheCleanupCheckMinInterval: process.env.CACHE_CLEANUP_CHECK_MIN_INTERVAL || "10m",
+  cacheTouchOnHit: toBool(process.env.CACHE_TOUCH_ON_HIT, true),
+  cacheTouchMinInterval: process.env.CACHE_TOUCH_MIN_INTERVAL || "1d",
+  cacheRetentionStart: process.env.CACHE_RETENTION_START || "10d",
+  cacheRetentionMin: process.env.CACHE_RETENTION_MIN || "1d",
+  cacheDiskFreeTrigger: process.env.CACHE_DISK_FREE_TRIGGER || "20G",
+  cacheDiskFreeTarget: process.env.CACHE_DISK_FREE_TARGET || "25G",
+  cacheMaxSize: process.env.CACHE_MAX_SIZE || "",
+  cacheTargetSize: process.env.CACHE_TARGET_SIZE || "",
   downloadLogDir: path.resolve(configBaseDir, process.env.DOWNLOAD_LOG_DIR || "data/logs/downloads"),
-  logRetentionDays: Math.max(1, toInt(process.env.LOG_RETENTION_DAYS, 7)),
+  logRetention,
+  logRetentionDays,
   logToStdout: toBool(process.env.LOG_TO_STDOUT, true),
   logConnectEvents: toBool(process.env.LOG_CONNECT_EVENTS, false),
   certDir: path.resolve(configBaseDir, process.env.CERT_DIR || "data/certs"),

package/src/index.js

@@ -8,6 +8,7 @@ import { startRepoServer } from "./repo/repo-server.js";
 import { getTrustStoreCommands } from "./cert/truststore-utils.js";
 import { UpstreamProxyManager } from "./proxy/upstream-proxy.js";
 import { MavenAffinityIndex } from "./cache/maven-affinity-index.js";
+import { CacheCleanupManager } from "./cache/cache-cleanup-manager.js";
 import { installConsoleLogFileMirror, installGlobalErrorLogging } from "./common/console-log-file.js";
 
 installConsoleLogFileMirror({
@@ -85,6 +86,8 @@ async function main() {
   const upstreamProxyManager = new UpstreamProxyManager(config, matchesDomain);
   const mavenAffinityIndex = new MavenAffinityIndex(config);
   await mavenAffinityIndex.init();
+  const cacheCleanupManager = new CacheCleanupManager(config);
+  await cacheCleanupManager.init();
 
   const downloader = new Downloader(config, matchesDomain, upstreamProxyManager);
 
@@ -95,8 +98,9 @@ async function main() {
     matchesDomain,
     upstreamProxyManager,
     mavenAffinityIndex,
+    cacheCleanupManager,
   );
-  const repoServer = startRepoServer(config, downloader);
+  const repoServer = startRepoServer(config, downloader, cacheCleanupManager);
 
   await Promise.all([
     waitForServerListening(proxyServer, "proxy server"),
@@ -119,18 +123,29 @@ async function main() {
   startupInfo(`[maven-proxy] cache npm  : ${config.npmCacheDir}`);
   startupInfo(`[maven-proxy] cache other: ${config.genericCacheDir}`);
   startupInfo(`[maven-proxy] log dir: ${config.downloadLogDir}`);
-  startupInfo(`[maven-proxy] log retention days: ${config.logRetentionDays}`);
+  startupInfo(`[maven-proxy] log retention: ${config.logRetention} (${config.logRetentionDays}d)`);
   startupInfo(`[maven-proxy] log to stdout: ${config.logToStdout}`);
   startupInfo(`[maven-proxy] log connect events: ${config.logConnectEvents}`);
   startupInfo(`[maven-proxy] outbound keep-alive: ${config.outboundKeepAlive}`);
-  startupInfo(`[maven-proxy] outbound keepAlive(seconds): ${config.outboundKeepAliveMsecs / 1000}`);
+  startupInfo(`[maven-proxy] outbound keepAlive interval: ${config.outboundKeepAliveInterval}`);
   startupInfo(`[maven-proxy] outbound maxSockets: ${config.outboundMaxSockets}`);
   startupInfo(`[maven-proxy] outbound maxFreeSockets: ${config.outboundMaxFreeSockets}`);
   startupInfo(`[maven-proxy] maven affinity enabled: ${config.mavenAffinityEnabled}`);
   startupInfo(`[maven-proxy] maven affinity index dir: ${config.mavenAffinityIndexDir}`);
-  startupInfo(`[maven-proxy] maven negative cache ttl(hours): ${config.mavenNegativeCacheTtlMs / (60 * 60 * 1000)}`);
-  startupInfo(`[maven-proxy] maven affinity flush interval(seconds): ${config.mavenAffinityFlushIntervalMs / 1000}`);
+  startupInfo(`[maven-proxy] maven negative cache ttl: ${config.mavenNegativeCacheTtl}`);
+  startupInfo(`[maven-proxy] maven affinity flush interval: ${config.mavenAffinityFlushInterval}`);
+  startupInfo(`[maven-proxy] download timeout: ${config.downloadTimeout}`);
   startupInfo(`[maven-proxy] maven affinity event max(MB): ${config.mavenAffinityEventMaxBytes / (1024 * 1024)}`);
+  startupInfo(`[maven-proxy] cache cleanup enabled: ${config.cacheCleanupEnabled}`);
+  startupInfo(`[maven-proxy] cache cleanup daily at: ${config.cacheCleanupDailyAt}`);
+  startupInfo(`[maven-proxy] cache touch on hit: ${config.cacheTouchOnHit}`);
+  startupInfo(`[maven-proxy] cache touch min interval: ${config.cacheTouchMinInterval}`);
+  startupInfo(`[maven-proxy] cache retention start: ${config.cacheRetentionStart}`);
+  startupInfo(`[maven-proxy] cache retention min: ${config.cacheRetentionMin}`);
+  startupInfo(`[maven-proxy] cache disk free trigger: ${config.cacheDiskFreeTrigger}`);
+  startupInfo(`[maven-proxy] cache disk free target: ${config.cacheDiskFreeTarget}`);
+  startupInfo(`[maven-proxy] cache max size: ${config.cacheMaxSize || "(disabled)"}`);
+  startupInfo(`[maven-proxy] cache target size: ${config.cacheTargetSize || "(disabled)"}`);
   startupInfo(`[maven-proxy] root cert : ${config.rootCertPath}`);
   startupInfo(`[maven-proxy] repo fallback repos: ${(config.repoFallbackRepos || []).join(",") || "(none)"}`);
   if (config.upstreamProxyUrl || config.upstreamHttpProxyUrl || config.upstreamHttpsProxyUrl) {
@@ -151,6 +166,7 @@ async function main() {
     mitmHttpServer.close();
     repoServer.close();
     upstreamProxyManager.destroy();
+    void cacheCleanupManager.destroy();
     void mavenAffinityIndex.destroy();
   };
 

package/src/proxy/proxy-http-handler.js

@@ -101,13 +101,17 @@ function buildUrl(req, forcedProtocol = null) {
   return new URL(`${protocol}//${host}${raw}`);
 }
 
-async function serveFile(res, req, filePath) {
+async function serveFile(res, req, filePath, cacheCleanupManager = null) {
   const stats = await statIfFile(filePath);
   if (!stats) {
     sendText(res, 404, "Not Found");
     return;
   }
 
+  if (cacheCleanupManager) {
+    cacheCleanupManager.touchFileOnHit(filePath);
+  }
+
   res.setHeader("content-length", String(stats.size));
   if (!res.hasHeader("x-cache")) {
     res.setHeader("x-cache", "HIT");
@@ -171,6 +175,7 @@ export function createHttpRequestHandler({
   upstreamProxyManager = null,
   matchesDomain,
   mavenAffinityIndex = null,
+  cacheCleanupManager = null,
 }) {
   return async function handleHttpRequestPath(req, res, forcedProtocol = null) {
     let urlObj;
@@ -210,7 +215,7 @@ export function createHttpRequestHandler({
     const existing = await statIfFile(cachePath);
     if (existing) {
       console.log(`[proxy] local cache hit host=${urlObj.hostname} path=${urlObj.pathname}`);
-      await serveFile(res, req, cachePath);
+      await serveFile(res, req, cachePath, cacheCleanupManager);
       return;
     }
 
@@ -219,7 +224,7 @@ export function createHttpRequestHandler({
         const preferredPath = await mavenAffinityIndex.resolvePreferredCachePath(canonical.canonicalKey);
         if (preferredPath) {
           console.log(`[proxy] affinity hit canonical=${canonical.canonicalKey} host=${urlObj.hostname}`);
-          await serveFile(res, req, preferredPath);
+          await serveFile(res, req, preferredPath, cacheCleanupManager);
           return;
         }
       }
@@ -233,6 +238,9 @@ export function createHttpRequestHandler({
 
     try {
       console.log(`[proxy] local cache miss host=${urlObj.hostname} path=${urlObj.pathname}`);
+      if (cacheCleanupManager) {
+        await cacheCleanupManager.checkAndCleanupIfNeeded("cache-miss");
+      }
       await fs.promises.mkdir(path.dirname(cachePath), { recursive: true });
       await downloader.ensureCached(urlObj, cachePath, req.headers);
 
@@ -247,7 +255,7 @@ export function createHttpRequestHandler({
       }
 
       res.setHeader("x-cache", "MISS");
-      await serveFile(res, req, cachePath);
+      await serveFile(res, req, cachePath, cacheCleanupManager);
     } catch (error) {
       if (
         canonical &&

package/src/proxy/proxy-server.js

@@ -19,6 +19,7 @@ export function startProxyServer(
   matchesDomain,
   upstreamProxyManager = null,
   mavenAffinityIndex = null,
+  cacheCleanupManager = null,
 ) {
   const handleHttpRequestPath = createHttpRequestHandler({
     config,
@@ -26,6 +27,7 @@ export function startProxyServer(
     upstreamProxyManager,
     matchesDomain,
     mavenAffinityIndex,
+    cacheCleanupManager,
   });
   const mitmHttpServer = createMitmHttpServer(handleHttpRequestPath);
 

package/src/repo/repo-server.js

@@ -41,7 +41,7 @@ function buildCandidateRelativePaths(relativePath) {
   return [...new Set(candidates.filter(Boolean))];
 }
 
-async function ensureFromRemoteRepos(config, downloader, filePath, relativePath) {
+async function ensureFromRemoteRepos(config, downloader, filePath, relativePath, cacheCleanupManager = null) {
   if (!downloader) {
     return null;
   }
@@ -60,6 +60,9 @@ async function ensureFromRemoteRepos(config, downloader, filePath, relativePath)
       const remoteUrl = buildRemoteUrl(repoBase, candidatePath);
 
       try {
+        if (cacheCleanupManager) {
+          await cacheCleanupManager.checkAndCleanupIfNeeded("repo-cache-miss");
+        }
         console.log(`[repo] cache miss, try remote ${remoteUrl.href}`);
         await downloader.ensureCached(remoteUrl, filePath, {});
         return await statIfExists(filePath);
@@ -79,7 +82,7 @@ async function ensureFromRemoteRepos(config, downloader, filePath, relativePath)
   return null;
 }
 
-export function startRepoServer(config, downloader = null) {
+export function startRepoServer(config, downloader = null, cacheCleanupManager = null) {
   const server = http.createServer(async (req, res) => {
     try {
       const urlObj = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
@@ -88,7 +91,7 @@ export function startRepoServer(config, downloader = null) {
       let stats = await statIfExists(filePath);
 
       if (!stats || !stats.isFile()) {
-        stats = await ensureFromRemoteRepos(config, downloader, filePath, relativePath);
+        stats = await ensureFromRemoteRepos(config, downloader, filePath, relativePath, cacheCleanupManager);
       }
 
       if (!stats || !stats.isFile()) {
@@ -100,6 +103,10 @@ export function startRepoServer(config, downloader = null) {
       res.setHeader("content-length", String(stats.size));
       res.setHeader("cache-control", "public, max-age=3600");
 
+      if (cacheCleanupManager) {
+        cacheCleanupManager.touchFileOnHit(filePath);
+      }
+
       if (req.method === "HEAD") {
         res.writeHead(200);
         res.end();