maven-proxy 1.1.0 → 1.2.0

package/README.md

@@ -185,8 +185,8 @@ npm install
 2. Configure environment variables as needed.
 
 Notes:
-- Development mode (default): npm start loads .env first, then .evn as fallback alias.
-- User mode (CLI default): npx maven-proxy or global command uses ~/maven-proxy/config.
+- Development mode (default): npm start loads config.properties in the project root.
+- User mode (CLI default): npx maven-proxy or global command uses ~/maven-proxy/config.properties.
 - Override mode with MAVEN_PROXY_CONFIG_MODE as development or user.
 - Override config file path with MAVEN_PROXY_CONFIG_FILE.
 - JAVA_HOME supports auto-detection:
@@ -267,6 +267,11 @@ Environment variables:
 - 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_TO_STDOUT: whether to also print logs to stdout/stderr.
+- OUTBOUND_KEEP_ALIVE: enable outbound keep-alive connection pooling.
+- OUTBOUND_KEEP_ALIVE_SECONDS: keep-alive interval in seconds.
+- OUTBOUND_MAX_SOCKETS: max outbound sockets per origin.
+- OUTBOUND_MAX_FREE_SOCKETS: max idle outbound sockets per origin.
 - 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.
@@ -294,10 +299,15 @@ Priority:
 - `MAVEN_REPO_DOMAINS`: Domains treated as Maven ecosystem for cache routing (wildcards supported).
 - `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_BYTES`: Minimum size threshold to trigger multi-thread download.
-- `DOWNLOAD_TIMEOUT_MS`: Upstream request timeout in milliseconds.
-- `DOWNLOAD_LOG_DIR`: Directory for download/console logs.
+- `MULTI_THREAD_MIN_SIZE_MB`: Minimum size threshold to trigger multi-thread download (MB).
+- `DOWNLOAD_TIMEOUT_SECONDS`: Upstream request timeout in seconds.
+- `DOWNLOAD_LOG_DIR`: Directory for unified app/error logs.
 - `LOG_RETENTION_DAYS`: Number of days to keep log files.
+- `LOG_TO_STDOUT`: Whether to also print logs to stdout/stderr. Default `true`.
+- `OUTBOUND_KEEP_ALIVE`: Enable outbound keep-alive connection pooling. Default `true`.
+- `OUTBOUND_KEEP_ALIVE_SECONDS`: Keep-alive interval in seconds. Default `1`.
+- `OUTBOUND_MAX_SOCKETS`: Max outbound sockets per origin. Default `64`.
+- `OUTBOUND_MAX_FREE_SOCKETS`: Max idle outbound sockets per origin. Default `16`.
 - `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.
@@ -388,7 +398,7 @@ maven-proxy
 ```
 
 Default CLI config path:
-- ~/maven-proxy/config
+- ~/maven-proxy/config.properties
 
 Common commands:
 - maven-proxy --config /path/to/config

package/bin/maven-proxy.js

@@ -6,7 +6,7 @@ import net from "node:net";
 import { spawnSync } from "node:child_process";
 
 const defaultConfigDir = path.resolve(os.homedir(), "maven-proxy");
-const defaultConfigFile = path.join(defaultConfigDir, "config");
+const defaultConfigFile = path.join(defaultConfigDir, "config.properties");
 
 function normalizeMode(value) {
   const normalized = String(value || "").trim().toLowerCase();
@@ -44,7 +44,7 @@ function resolveEffectiveMode(options) {
     return forced;
   }
 
-  // CLI defaults to user mode to load ~/maven-proxy/config unless explicitly overridden.
+  // CLI defaults to user mode to load ~/maven-proxy/config.properties unless explicitly overridden.
   return "user";
 }
 
@@ -62,7 +62,7 @@ function printHelp() {
   console.log("  npx maven-proxy");
   console.log("  maven-proxy init-config");
   console.log("  maven-proxy start --mode development");
-  console.log("  maven-proxy --config ~/maven-proxy/config");
+  console.log("  maven-proxy --config ~/maven-proxy/config.properties");
   console.log("  maven-proxy truststore print");
   console.log("  maven-proxy truststore merge --source ./a.jks --target ./b.jks");
   console.log("  maven-proxy doctor");
@@ -149,10 +149,20 @@ function getDefaultConfigTemplate() {
     "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_BYTES=1048576",
-    "DOWNLOAD_TIMEOUT_MS=60000",
+    "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=",
@@ -304,7 +314,7 @@ async function runDoctor(options) {
     printDoctorLine("WARN", "config file", `not found, expected ${config.defaultUserConfigPath}`);
   } else {
     warnings.push("development config file missing");
-    printDoctorLine("WARN", "config file", "no .env/.evn loaded, using defaults");
+    printDoctorLine("WARN", "config file", "no config.properties loaded, using defaults");
   }
 
   const keytool = checkKeytool();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maven-proxy",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Maven proxy with cache, HTTPS MITM for selected domains, and local repo publishing",
   "main": "src/index.js",
   "bin": {
@@ -33,7 +33,9 @@
     "npm:version:patch": "npm version patch",
     "npm:view:version": "npm view maven-proxy version",
     "npm:view:dist-tags": "npm view maven-proxy dist-tags",
-    "test": "node -e \"console.log('No tests yet')\""
+    "replay:affinity": "node --test test/replay-affinity.test.js",
+    "test:replay": "node --test test/replay-affinity.test.js",
+    "test": "node --test test/*.test.js"
   },
   "keywords": [],
   "author": "",

package/src/cache/downloader.js

@@ -3,7 +3,6 @@ import http from "node:http";
 import https from "node:https";
 import path from "node:path";
 import { pipeline } from "node:stream/promises";
-import { DownloadLogWriter } from "../common/download-log-writer.js";
 
 const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);
 const MAX_REDIRECTS = 5;
@@ -288,7 +287,6 @@ export class Downloader {
     this.domainMatcher = domainMatcher;
     this.upstreamProxyManager = upstreamProxyManager;
     this.inflight = new Map();
-    this.downloadLogWriter = new DownloadLogWriter(config.downloadLogDir, config.logRetentionDays);
   }
 
   logDownload(event, urlObj, details = {}) {
@@ -299,7 +297,6 @@ export class Downloader {
       .join(" ");
 
     console.log(`[downloader] ${event} url=${url}${detailText ? ` ${detailText}` : ""}`);
-    this.downloadLogWriter.write(event, url, details);
   }
 
   async ensureCached(urlObj, finalPath, requestHeaders = {}) {
@@ -326,6 +323,8 @@ export class Downloader {
   }
 
   async #downloadAtomic(urlObj, finalPath, requestHeaders) {
+    const startedAt = Date.now();
+
     await fs.promises.mkdir(path.dirname(finalPath), { recursive: true });
     const tempPath = `${finalPath}.temp`;
     await removeIfExists(tempPath);
@@ -388,6 +387,14 @@ export class Downloader {
 
       await verifyFileSize(tempPath, metadata.contentLength);
       await fs.promises.rename(tempPath, finalPath);
+
+      const finalStats = await fs.promises.stat(finalPath);
+      this.logDownload("download succeeded", downloadUrl, {
+        host: hostname,
+        targetPath: finalPath,
+        size: finalStats.size,
+        elapsedMs: Date.now() - startedAt,
+      });
     } catch (error) {
       if (isLocalFsWriteError(error)) {
         if (!error.statusCode) {

package/src/cache/maven-affinity-index.js

@@ -0,0 +1,393 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function toPositiveInt(value, fallback) {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function toBool(value, fallback) {
+  if (value == null || value === "") {
+    return fallback;
+  }
+
+  return ["1", "true", "yes", "on"].includes(String(value).toLowerCase());
+}
+
+function nowMs() {
+  return Date.now();
+}
+
+function readJsonFile(filePath, fallback) {
+  if (!fs.existsSync(filePath)) {
+    return fallback;
+  }
+
+  try {
+    const text = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(text);
+  } catch {
+    return fallback;
+  }
+}
+
+function serializeSnapshot(positiveMap, negativeMap, conflictMap) {
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    positive: [...positiveMap.entries()],
+    negative: [...negativeMap.entries()],
+    conflicts: [...conflictMap.entries()],
+  };
+}
+
+function normalizeRequestPath(pathname) {
+  return String(pathname || "")
+    .replace(/\\/g, "/")
+    .replace(/\/+/g, "/")
+    .replace(/^\/+/, "")
+    .trim();
+}
+
+function buildNegativeScope(urlObj) {
+  if (!urlObj || typeof urlObj !== "object") {
+    return "";
+  }
+
+  const protocol = urlObj.protocol === "https:" ? "https:" : "http:";
+  const host = String(urlObj.host || "").toLowerCase();
+  const pathname = normalizeRequestPath(urlObj.pathname || "");
+  return `${protocol}//${host}/${pathname}`;
+}
+
+function buildNegativeKey(scope, canonicalKey) {
+  return `${String(scope || "").toLowerCase()}|${canonicalKey}`;
+}
+
+export class MavenAffinityIndex {
+  constructor(config) {
+    this.enabled = toBool(config.mavenAffinityEnabled, true);
+    this.indexDir = config.mavenAffinityIndexDir;
+    this.negativeTtlMs = toPositiveInt(config.mavenNegativeCacheTtlMs, 24 * 60 * 60 * 1000);
+    this.flushIntervalMs = toPositiveInt(config.mavenAffinityFlushIntervalMs, 5000);
+    this.maxEventBytes = toPositiveInt(config.mavenAffinityEventMaxBytes, 8 * 1024 * 1024);
+
+    this.snapshotPath = path.join(this.indexDir, "maven-affinity.snapshot.json");
+    this.eventLogPath = path.join(this.indexDir, "maven-affinity.events.log");
+
+    this.positive = new Map();
+    this.negative = new Map();
+    this.conflicts = new Map();
+
+    this.pendingEvents = [];
+    this.flushTimer = null;
+    this.flushing = false;
+    this.dirtySinceSnapshot = false;
+  }
+
+  async init() {
+    if (!this.enabled) {
+      return;
+    }
+
+    await fs.promises.mkdir(this.indexDir, { recursive: true });
+    this.#loadSnapshot();
+    this.#replayEventLog();
+
+    this.flushTimer = setInterval(() => {
+      this.flush().catch((error) => {
+        console.error(`[affinity] flush failed: ${error.message}`);
+      });
+    }, this.flushIntervalMs);
+
+    if (typeof this.flushTimer.unref === "function") {
+      this.flushTimer.unref();
+    }
+  }
+
+  #loadSnapshot() {
+    const snapshot = readJsonFile(this.snapshotPath, null);
+    if (!snapshot || typeof snapshot !== "object") {
+      return;
+    }
+
+    for (const [key, value] of snapshot.positive || []) {
+      this.positive.set(key, value);
+    }
+
+    const currentTime = nowMs();
+    for (const [key, value] of snapshot.negative || []) {
+      if (value?.expireAt && value.expireAt > currentTime) {
+        this.negative.set(key, value);
+      }
+    }
+
+    for (const [key, value] of snapshot.conflicts || []) {
+      this.conflicts.set(key, value);
+    }
+  }
+
+  #replayEventLog() {
+    if (!fs.existsSync(this.eventLogPath)) {
+      return;
+    }
+
+    let raw = "";
+    try {
+      raw = fs.readFileSync(this.eventLogPath, "utf8");
+    } catch {
+      return;
+    }
+
+    const lines = raw.split(/\r?\n/).filter(Boolean);
+    for (const line of lines) {
+      try {
+        const event = JSON.parse(line);
+        this.#applyEvent(event, false);
+      } catch {
+        // ignore invalid line
+      }
+    }
+  }
+
+  #enqueueEvent(type, payload) {
+    this.pendingEvents.push(JSON.stringify({ t: nowMs(), type, payload }));
+    this.dirtySinceSnapshot = true;
+  }
+
+  #applyEvent(event, append = true) {
+    if (!event || typeof event !== "object") {
+      return;
+    }
+
+    const { type, payload } = event;
+    if (!type || !payload || typeof payload !== "object") {
+      return;
+    }
+
+    if (type === "positive_upsert") {
+      this.positive.set(payload.key, payload.value);
+      if (append) {
+        this.#enqueueEvent(type, payload);
+      }
+      return;
+    }
+
+    if (type === "positive_remove") {
+      this.positive.delete(payload.key);
+      if (append) {
+        this.#enqueueEvent(type, payload);
+      }
+      return;
+    }
+
+    if (type === "negative_upsert") {
+      if (payload.value?.expireAt > nowMs()) {
+        this.negative.set(payload.key, payload.value);
+      } else {
+        this.negative.delete(payload.key);
+      }
+      if (append) {
+        this.#enqueueEvent(type, payload);
+      }
+      return;
+    }
+
+    if (type === "negative_remove") {
+      this.negative.delete(payload.key);
+      if (append) {
+        this.#enqueueEvent(type, payload);
+      }
+      return;
+    }
+
+    if (type === "conflict_set") {
+      this.conflicts.set(payload.key, payload.value);
+      if (append) {
+        this.#enqueueEvent(type, payload);
+      }
+      return;
+    }
+
+    if (type === "conflict_clear") {
+      this.conflicts.delete(payload.key);
+      if (append) {
+        this.#enqueueEvent(type, payload);
+      }
+    }
+  }
+
+  async resolvePreferredCachePath(canonicalKey) {
+    if (!this.enabled || !canonicalKey) {
+      return "";
+    }
+
+    if (this.conflicts.has(canonicalKey)) {
+      return "";
+    }
+
+    const existing = this.positive.get(canonicalKey);
+    if (!existing?.cachePath) {
+      return "";
+    }
+
+    try {
+      const stats = await fs.promises.stat(existing.cachePath);
+      if (!stats.isFile()) {
+        throw new Error("not-file");
+      }
+      return existing.cachePath;
+    } catch {
+      this.#applyEvent({
+        type: "positive_remove",
+        payload: { key: canonicalKey },
+      });
+      return "";
+    }
+  }
+
+  shouldSkipRequest(canonicalKey, urlObj) {
+    const scope = buildNegativeScope(urlObj);
+    if (!this.enabled || !canonicalKey || !scope) {
+      return false;
+    }
+
+    const key = buildNegativeKey(scope, canonicalKey);
+    const entry = this.negative.get(key);
+    if (!entry) {
+      return false;
+    }
+
+    if (entry.expireAt <= nowMs()) {
+      this.#applyEvent({
+        type: "negative_remove",
+        payload: { key },
+      });
+      return false;
+    }
+
+    return true;
+  }
+
+  recordSuccess({ canonicalKey, host, cachePath, fileName }) {
+    if (!this.enabled || !canonicalKey || !cachePath || !fileName) {
+      return;
+    }
+
+    const previous = this.positive.get(canonicalKey);
+    if (previous && previous.fileName !== fileName) {
+      this.#applyEvent({
+        type: "conflict_set",
+        payload: {
+          key: canonicalKey,
+          value: {
+            reason: "file-name-mismatch",
+            updatedAt: nowMs(),
+            previousFileName: previous.fileName,
+            currentFileName: fileName,
+          },
+        },
+      });
+
+      this.#applyEvent({
+        type: "positive_remove",
+        payload: { key: canonicalKey },
+      });
+      return;
+    }
+
+    this.#applyEvent({
+      type: "positive_upsert",
+      payload: {
+        key: canonicalKey,
+        value: {
+          cachePath,
+          fileName,
+          host: String(host || "").toLowerCase(),
+          updatedAt: nowMs(),
+        },
+      },
+    });
+
+    if (host) {
+      const negativeKey = buildNegativeKey(host, canonicalKey);
+      if (this.negative.has(negativeKey)) {
+        this.#applyEvent({
+          type: "negative_remove",
+          payload: { key: negativeKey },
+        });
+      }
+    }
+  }
+
+  recordNegative({ canonicalKey, urlObj, statusCode = 404, ttlMs = this.negativeTtlMs }) {
+    const scope = buildNegativeScope(urlObj);
+    if (!this.enabled || !canonicalKey || !scope) {
+      return;
+    }
+
+    const expireAt = nowMs() + toPositiveInt(ttlMs, this.negativeTtlMs);
+    const key = buildNegativeKey(scope, canonicalKey);
+    this.#applyEvent({
+      type: "negative_upsert",
+      payload: {
+        key,
+        value: {
+          scope,
+          statusCode,
+          expireAt,
+          updatedAt: nowMs(),
+        },
+      },
+    });
+  }
+
+  async flush() {
+    if (!this.enabled || this.flushing) {
+      return;
+    }
+
+    this.flushing = true;
+    try {
+      if (this.pendingEvents.length > 0) {
+        const text = `${this.pendingEvents.join("\n")}\n`;
+        this.pendingEvents = [];
+        await fs.promises.appendFile(this.eventLogPath, text, "utf8");
+      }
+
+      const stats = await fs.promises.stat(this.eventLogPath).catch(() => null);
+      const needsSnapshot = this.dirtySinceSnapshot && (!stats || stats.size >= this.maxEventBytes);
+
+      if (needsSnapshot) {
+        await this.#writeSnapshotAndResetEventLog();
+      }
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  async #writeSnapshotAndResetEventLog() {
+    const snapshot = serializeSnapshot(this.positive, this.negative, this.conflicts);
+    const tempPath = `${this.snapshotPath}.tmp`;
+    await fs.promises.writeFile(tempPath, `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+    await fs.promises.rename(tempPath, this.snapshotPath);
+    await fs.promises.writeFile(this.eventLogPath, "", "utf8");
+    this.dirtySinceSnapshot = false;
+  }
+
+  async destroy() {
+    if (!this.enabled) {
+      return;
+    }
+
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+
+    await this.flush();
+    if (this.dirtySinceSnapshot) {
+      await this.#writeSnapshotAndResetEventLog();
+    }
+  }
+}

package/src/common/console-log-file.js

@@ -4,45 +4,75 @@ import { DailyLogFile } from "./daily-log-file.js";
 const MIRROR_INSTALLED = Symbol.for("maven-proxy.console-log-file.installed");
 const GLOBAL_ERROR_HOOK_INSTALLED = Symbol.for("maven-proxy.global-error-hook.installed");
 
-function mirrorConsoleMethod({ level, originalMethod, logFile }) {
+function mirrorConsoleMethod({
+  level,
+  originalMethod,
+  appLogFile,
+  errorLogFile,
+  outputToConsole,
+}) {
   return (...args) => {
-    originalMethod(...args);
+    if (outputToConsole) {
+      originalMethod(...args);
+    }
 
     const line = `[${new Date().toISOString()}] [${level}] ${util.format(...args)}`;
-    logFile.appendLine(line).catch((error) => {
+    appLogFile.appendLine(line).catch((error) => {
       process.stderr.write(`[maven-proxy] write console log failed: ${error.message}\n`);
     });
+
+    if (level === "ERROR") {
+      errorLogFile.appendLine(line).catch((error) => {
+        process.stderr.write(`[maven-proxy] write error log failed: ${error.message}\n`);
+      });
+    }
   };
 }
 
-export function installConsoleLogFileMirror({ logDir, retentionDays = 7 }) {
+export function installConsoleLogFileMirror({
+  logDir,
+  retentionDays = 7,
+  outputToConsole = true,
+}) {
   if (globalThis[MIRROR_INSTALLED]) {
     return;
   }
   globalThis[MIRROR_INSTALLED] = true;
 
-  const logFile = new DailyLogFile({
+  const appLogFile = new DailyLogFile({
+    logDir,
+    filePrefix: "app",
+    retentionDays,
+  });
+
+  const errorLogFile = new DailyLogFile({
     logDir,
-    filePrefix: "console",
+    filePrefix: "error",
     retentionDays,
   });
 
   console.log = mirrorConsoleMethod({
     level: "INFO",
     originalMethod: console.log.bind(console),
-    logFile,
+    appLogFile,
+    errorLogFile,
+    outputToConsole,
   });
 
   console.warn = mirrorConsoleMethod({
     level: "WARN",
     originalMethod: console.warn.bind(console),
-    logFile,
+    appLogFile,
+    errorLogFile,
+    outputToConsole,
   });
 
   console.error = mirrorConsoleMethod({
     level: "ERROR",
     originalMethod: console.error.bind(console),
-    logFile,
+    appLogFile,
+    errorLogFile,
+    outputToConsole,
   });
 }
 

package/src/common/maven-canonical.js

@@ -0,0 +1,151 @@
+function safeDecode(pathname) {
+  try {
+    return decodeURIComponent(pathname || "/");
+  } catch {
+    return pathname || "/";
+  }
+}
+
+function escapeRegex(value) {
+  return String(value || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function normalizePathname(pathname) {
+  return String(pathname || "")
+    .replace(/\\/g, "/")
+    .replace(/^\/+/, "")
+    .replace(/\/+/g, "/")
+    .trim();
+}
+
+function stripKnownPrefixes(relativePath) {
+  const raw = normalizePathname(relativePath);
+  if (!raw) {
+    return [];
+  }
+
+  const candidates = new Set([raw]);
+
+  if (raw.toLowerCase().startsWith("maven2/")) {
+    candidates.add(raw.slice("maven2/".length));
+  }
+
+  if (raw.toLowerCase().startsWith("m2/")) {
+    candidates.add(raw.slice("m2/".length));
+  }
+
+  const maven2Marker = raw.toLowerCase().indexOf("/maven2/");
+  if (maven2Marker >= 0) {
+    candidates.add(raw.slice(maven2Marker + "/maven2/".length));
+  }
+
+  const m2Marker = raw.toLowerCase().indexOf("/m2/");
+  if (m2Marker >= 0) {
+    candidates.add(raw.slice(m2Marker + "/m2/".length));
+  }
+
+  const patterns = [
+    /^repository\/[^/]+\/(.+)$/i,
+    /^artifactory\/[^/]+\/(.+)$/i,
+    /^nexus\/content\/repositories\/[^/]+\/(.+)$/i,
+    /^repositories\/[^/]+\/(.+)$/i,
+  ];
+
+  for (const pattern of patterns) {
+    const match = raw.match(pattern);
+    if (match?.[1]) {
+      candidates.add(match[1]);
+    }
+  }
+
+  const normalizedCandidates = [...candidates].map((item) => normalizePathname(item)).filter(Boolean);
+  normalizedCandidates.sort((left, right) => left.split("/").length - right.split("/").length);
+  return normalizedCandidates;
+}
+
+function isSafePathSegment(segment) {
+  return /^[A-Za-z0-9_.+-]+$/.test(String(segment || ""));
+}
+
+function isReleaseVersion(version) {
+  return !String(version || "").toUpperCase().endsWith("-SNAPSHOT");
+}
+
+function matchReleaseFileName(artifact, version, fileName) {
+  if (/-SNAPSHOT(?=\.|-)/i.test(fileName)) {
+    return false;
+  }
+
+  const escapedArtifact = escapeRegex(artifact);
+  const escapedVersion = escapeRegex(version);
+  const pattern = new RegExp(
+    `^${escapedArtifact}-${escapedVersion}(?:-[A-Za-z0-9_.+:-]+)?\\.(pom|jar|module|aar|war)(?:\\.(sha1|sha256|sha512|md5|asc))?$`,
+    "i",
+  );
+
+  return pattern.test(fileName);
+}
+
+function tryParseCandidate(relativePath) {
+  const normalized = normalizePathname(relativePath);
+  const parts = normalized.split("/").filter(Boolean);
+  if (parts.length < 4) {
+    return null;
+  }
+
+  const fileName = parts[parts.length - 1];
+  const version = parts[parts.length - 2];
+  const artifact = parts[parts.length - 3];
+  const groupParts = parts.slice(0, -3);
+
+  if (!artifact || !version || !fileName || groupParts.length === 0) {
+    return null;
+  }
+
+  if (!isSafePathSegment(artifact) || !isSafePathSegment(version) || !isSafePathSegment(fileName)) {
+    return null;
+  }
+
+  if (!groupParts.every((segment) => isSafePathSegment(segment))) {
+    return null;
+  }
+
+  if (!isReleaseVersion(version)) {
+    return null;
+  }
+
+  if (!matchReleaseFileName(artifact, version, fileName)) {
+    return null;
+  }
+
+  const groupPath = groupParts.join("/");
+  const canonicalPath = `${groupPath}/${artifact}/${version}/${fileName}`;
+
+  return {
+    canonicalPath,
+    canonicalKey: canonicalPath,
+    groupPath,
+    artifact,
+    version,
+    fileName,
+    isRelease: true,
+  };
+}
+
+export function parseMavenReleaseCanonical(urlObj) {
+  if (!urlObj || typeof urlObj !== "object") {
+    return null;
+  }
+
+  const decodedPath = safeDecode(urlObj.pathname || "/");
+  const candidates = stripKnownPrefixes(decodedPath);
+
+  for (const candidate of candidates) {
+    const parsed = tryParseCandidate(candidate);
+    if (parsed) {
+      return parsed;
+    }
+  }
+
+  return null;
+}

package/src/config/config.js

@@ -6,7 +6,7 @@ import { detectJavaHome } from "../common/java-home.js";
 
 const cwd = process.cwd();
 const userConfigDir = path.resolve(os.homedir(), "maven-proxy");
-const defaultUserConfigPath = path.join(userConfigDir, "config");
+const defaultUserConfigPath = path.join(userConfigDir, "config.properties");
 
 function normalizeConfigMode(value) {
   const normalized = String(value || "").trim().toLowerCase();
@@ -55,8 +55,7 @@ function resolveConfigFilePath(configMode) {
 
   if (configMode === "development") {
     const devCandidates = [
-      path.resolve(cwd, ".env"),
-      path.resolve(cwd, ".evn"),
+      path.resolve(cwd, "config.properties"),
     ];
 
     for (const candidate of devCandidates) {
@@ -181,6 +180,13 @@ const defaultMavenRepoDomains = [
 
 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 mavenAffinityEventMaxBytes = Math.max(1, toInt(process.env.MAVEN_AFFINITY_EVENT_MAX_MB, 8)) * 1024 * 1024;
+
 export const config = {
   configMode,
   configBaseDir,
@@ -198,10 +204,20 @@ export const config = {
   mavenRepoDomains: toList(process.env.MAVEN_REPO_DOMAINS, [...new Set(defaultMavenRepoDomains)]),
   multiThreadDomains: toList(process.env.MULTI_THREAD_DOMAINS, ["repo1.maven.org"]),
   multiThreadCount: Math.max(1, toInt(process.env.MULTI_THREAD_COUNT, 4)),
-  multiThreadMinSizeBytes: Math.max(0, toInt(process.env.MULTI_THREAD_MIN_SIZE_BYTES, 1024 * 1024)),
-  downloadTimeoutMs: Math.max(1000, toInt(process.env.DOWNLOAD_TIMEOUT_MS, 60000)),
+  multiThreadMinSizeBytes,
+  downloadTimeoutMs,
+  outboundKeepAlive: toBool(process.env.OUTBOUND_KEEP_ALIVE, true),
+  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"),
+  mavenNegativeCacheTtlMs,
+  mavenAffinityFlushIntervalMs,
+  mavenAffinityEventMaxBytes,
   downloadLogDir: path.resolve(configBaseDir, process.env.DOWNLOAD_LOG_DIR || "data/logs/downloads"),
   logRetentionDays: Math.max(1, toInt(process.env.LOG_RETENTION_DAYS, 7)),
+  logToStdout: toBool(process.env.LOG_TO_STDOUT, true),
   certDir: path.resolve(configBaseDir, process.env.CERT_DIR || "data/certs"),
   rootCertPath: path.resolve(configBaseDir, process.env.ROOT_CERT_PATH || "data/certs/root-ca.crt"),
   rootKeyPath: path.resolve(configBaseDir, process.env.ROOT_KEY_PATH || "data/certs/root-ca.key.pem"),

package/src/index.js

@@ -7,11 +7,13 @@ import { startProxyServer } from "./proxy/proxy-server.js";
 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 { installConsoleLogFileMirror, installGlobalErrorLogging } from "./common/console-log-file.js";
 
 installConsoleLogFileMirror({
   logDir: config.downloadLogDir,
   retentionDays: config.logRetentionDays,
+  outputToConsole: config.logToStdout,
 });
 installGlobalErrorLogging();
 
@@ -34,6 +36,8 @@ async function main() {
   }
 
   const upstreamProxyManager = new UpstreamProxyManager(config, matchesDomain);
+  const mavenAffinityIndex = new MavenAffinityIndex(config);
+  await mavenAffinityIndex.init();
 
   const downloader = new Downloader(config, matchesDomain, upstreamProxyManager);
 
@@ -43,6 +47,7 @@ async function main() {
     downloader,
     matchesDomain,
     upstreamProxyManager,
+    mavenAffinityIndex,
   );
   const repoServer = startRepoServer(config, downloader);
 
@@ -61,8 +66,18 @@ async function main() {
   console.log(`[maven-proxy] cache maven: ${config.mavenCacheDir}`);
   console.log(`[maven-proxy] cache npm  : ${config.npmCacheDir}`);
   console.log(`[maven-proxy] cache other: ${config.genericCacheDir}`);
-  console.log(`[maven-proxy] download log: ${config.downloadLogDir}`);
+  console.log(`[maven-proxy] log dir: ${config.downloadLogDir}`);
   console.log(`[maven-proxy] log retention days: ${config.logRetentionDays}`);
+  console.log(`[maven-proxy] log to stdout: ${config.logToStdout}`);
+  console.log(`[maven-proxy] outbound keep-alive: ${config.outboundKeepAlive}`);
+  console.log(`[maven-proxy] outbound keepAlive(seconds): ${config.outboundKeepAliveMsecs / 1000}`);
+  console.log(`[maven-proxy] outbound maxSockets: ${config.outboundMaxSockets}`);
+  console.log(`[maven-proxy] outbound maxFreeSockets: ${config.outboundMaxFreeSockets}`);
+  console.log(`[maven-proxy] maven affinity enabled: ${config.mavenAffinityEnabled}`);
+  console.log(`[maven-proxy] maven affinity index dir: ${config.mavenAffinityIndexDir}`);
+  console.log(`[maven-proxy] maven negative cache ttl(hours): ${config.mavenNegativeCacheTtlMs / (60 * 60 * 1000)}`);
+  console.log(`[maven-proxy] maven affinity flush interval(seconds): ${config.mavenAffinityFlushIntervalMs / 1000}`);
+  console.log(`[maven-proxy] maven affinity event max(MB): ${config.mavenAffinityEventMaxBytes / (1024 * 1024)}`);
   console.log(`[maven-proxy] root cert : ${config.rootCertPath}`);
   console.log(`[maven-proxy] repo fallback repos: ${(config.repoFallbackRepos || []).join(",") || "(none)"}`);
   if (config.upstreamProxyUrl || config.upstreamHttpProxyUrl || config.upstreamHttpsProxyUrl) {
@@ -81,6 +96,8 @@ async function main() {
     proxyServer.close();
     mitmHttpServer.close();
     repoServer.close();
+    upstreamProxyManager.destroy();
+    void mavenAffinityIndex.destroy();
   };
 
   process.on("SIGINT", shutdown);

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

@@ -4,6 +4,7 @@ import https from "node:https";
 import path from "node:path";
 import { getCacheFilePath } from "../cache/cache-path.js";
 import { detectPackageEcosystem } from "../common/ecosystem.js";
+import { parseMavenReleaseCanonical } from "../common/maven-canonical.js";
 
 const LOCAL_FS_ERROR_CODES = new Set([
   "EACCES",
@@ -158,7 +159,13 @@ function forwardDirectRequest(req, res, urlObj, timeoutMs, upstreamProxyManager
   req.pipe(upstreamReq);
 }
 
-export function createHttpRequestHandler({ config, downloader, upstreamProxyManager = null, matchesDomain }) {
+export function createHttpRequestHandler({
+  config,
+  downloader,
+  upstreamProxyManager = null,
+  matchesDomain,
+  mavenAffinityIndex = null,
+}) {
   return async function handleHttpRequestPath(req, res, forcedProtocol = null) {
     let urlObj;
     try {
@@ -176,12 +183,18 @@ export function createHttpRequestHandler({ config, downloader, upstreamProxyMana
     }
 
     let cachePath;
+    let ecosystem;
+    let canonical = null;
     try {
-      const ecosystem = detectPackageEcosystem(urlObj, config, matchesDomain);
+      ecosystem = detectPackageEcosystem(urlObj, config, matchesDomain);
       cachePath = getCacheFilePath(config.cacheDir, urlObj, {
         ecosystem,
         includeHost: ecosystem !== "maven",
       });
+
+      if (ecosystem === "maven" && mavenAffinityIndex?.enabled) {
+        canonical = parseMavenReleaseCanonical(urlObj);
+      }
     } catch (error) {
       const message = `Invalid cache path: ${error.message}`;
       sendErrorText(res, 400, message, "proxy");
@@ -194,12 +207,49 @@ export function createHttpRequestHandler({ config, downloader, upstreamProxyMana
       return;
     }
 
+    if (canonical && mavenAffinityIndex) {
+      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);
+        return;
+      }
+
+      if (mavenAffinityIndex.shouldSkipRequest(canonical.canonicalKey, urlObj)) {
+        console.log(`[proxy] affinity negative skip canonical=${canonical.canonicalKey} host=${urlObj.hostname}`);
+        sendText(res, 404, "Not Found");
+        return;
+      }
+    }
+
     try {
       await fs.promises.mkdir(path.dirname(cachePath), { recursive: true });
       await downloader.ensureCached(urlObj, cachePath, req.headers);
+
+      if (canonical && mavenAffinityIndex) {
+        mavenAffinityIndex.recordSuccess({
+          canonicalKey: canonical.canonicalKey,
+          host: urlObj.hostname,
+          cachePath,
+          fileName: canonical.fileName,
+        });
+      }
+
       res.setHeader("x-cache", "MISS");
       await serveFile(res, req, cachePath);
     } catch (error) {
+      if (
+        canonical &&
+        mavenAffinityIndex &&
+        (error.statusCode === 404 || error.statusCode === 410)
+      ) {
+        mavenAffinityIndex.recordNegative({
+          canonicalKey: canonical.canonicalKey,
+          urlObj,
+          statusCode: error.statusCode,
+        });
+      }
+
       if (isLocalFsWriteError(error)) {
         if (!error.statusCode) {
           error.statusCode = 500;

package/src/proxy/proxy-server.js

@@ -12,12 +12,20 @@ function sendErrorText(res, statusCode, message) {
   sendText(res, statusCode, message);
 }
 
-export function startProxyServer(config, certManager, downloader, matchesDomain, upstreamProxyManager = null) {
+export function startProxyServer(
+  config,
+  certManager,
+  downloader,
+  matchesDomain,
+  upstreamProxyManager = null,
+  mavenAffinityIndex = null,
+) {
   const handleHttpRequestPath = createHttpRequestHandler({
     config,
     downloader,
     upstreamProxyManager,
     matchesDomain,
+    mavenAffinityIndex,
   });
   const mitmHttpServer = createMitmHttpServer(handleHttpRequestPath);
 

package/src/proxy/upstream-proxy.js

@@ -1,7 +1,23 @@
+import http from "node:http";
+import https from "node:https";
 import net from "node:net";
 import tls from "node:tls";
 import { ProxyAgent } from "proxy-agent";
 
+function toPositiveInt(value, fallback) {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function buildAgentOptions(config) {
+  return {
+    keepAlive: Boolean(config.outboundKeepAlive),
+    keepAliveMsecs: toPositiveInt(config.outboundKeepAliveMsecs, 1000),
+    maxSockets: toPositiveInt(config.outboundMaxSockets, 64),
+    maxFreeSockets: toPositiveInt(config.outboundMaxFreeSockets, 16),
+  };
+}
+
 function normalizeHostname(hostname) {
   return String(hostname || "")
     .trim()
@@ -64,6 +80,12 @@ export class UpstreamProxyManager {
     this.config = config;
     this.matchesDomain = matchesDomain;
     this.agentCache = new Map();
+    this.directHttpAgent = new http.Agent(buildAgentOptions(config));
+    this.directHttpsAgent = new https.Agent(buildAgentOptions(config));
+  }
+
+  getDirectAgentForProtocol(protocol) {
+    return protocol === "https:" ? this.directHttpsAgent : this.directHttpAgent;
   }
 
   shouldBypass(hostname) {
@@ -111,17 +133,21 @@ export class UpstreamProxyManager {
   }
 
   getAgentForUrl(urlObj) {
-    const proxyUrl = this.getProxyUrlFor(urlObj.protocol, urlObj.hostname);
+    const protocol = urlObj?.protocol === "https:" ? "https:" : "http:";
+    const hostname = String(urlObj?.hostname || "");
+    const proxyUrl = this.getProxyUrlFor(protocol, hostname);
+
     if (!proxyUrl) {
-      return undefined;
+      return this.getDirectAgentForProtocol(protocol);
     }
 
-    const cacheKey = `${proxyUrl}`;
+    const cacheKey = `proxy:${proxyUrl}`;
     if (!this.agentCache.has(cacheKey)) {
       // proxy-agent v6 expects resolver-style options for deterministic proxy routing.
       this.agentCache.set(
         cacheKey,
         new ProxyAgent({
+          ...buildAgentOptions(this.config),
           getProxyForUrl: () => proxyUrl,
         }),
       );
@@ -134,6 +160,18 @@ export class UpstreamProxyManager {
     return Boolean(this.getProxyUrlFor(protocol, hostname));
   }
 
+  destroy() {
+    for (const agent of this.agentCache.values()) {
+      if (typeof agent?.destroy === "function") {
+        agent.destroy();
+      }
+    }
+
+    this.agentCache.clear();
+    this.directHttpAgent.destroy();
+    this.directHttpsAgent.destroy();
+  }
+
   async createConnectTunnel(targetHost, targetPort, timeoutMs) {
     const proxyUrlText = this.getProxyUrlFor("https:", targetHost);
     if (!proxyUrlText) {

package/src/common/download-log-writer.js

@@ -1,27 +0,0 @@
-import { DailyLogFile } from "./daily-log-file.js";
-
-export class DownloadLogWriter {
-  constructor(logDir, retentionDays = 7) {
-    this.logFile = new DailyLogFile({
-      logDir,
-      filePrefix: "download",
-      retentionDays,
-    });
-  }
-
-  async append(event, url, details = {}) {
-    const record = {
-      time: new Date().toISOString(),
-      event,
-      url,
-      ...details,
-    };
-    await this.logFile.appendLine(JSON.stringify(record));
-  }
-
-  write(event, url, details = {}) {
-    this.append(event, url, details).catch((error) => {
-      console.warn(`[downloader] write download log failed: ${error.message}`);
-    });
-  }
-}