chore: Implement cache to aviod rate limiting.

Author: mheggelund

.github/workflows/publish.yaml

@@ -50,6 +50,25 @@ jobs:
       - name: Fixup module naming
         run: find jneqsim/neqsim -type f -name "*.pyi" -print0 | xargs -0  sed -i '' -e 's/neqsim./jneqsim.neqsim./g' || true
 
+      - name: Update NeqSim dependency version
+        run: |
+          NEQSIM_VERSION="${{ inputs.version }}"
+          echo "Updating NeqSim dependency to version '$NEQSIM_VERSION'"
+          
+          # Get the current version to use as fallback
+          CURRENT_VERSION=$(grep -o 'version: "[^"]*"' jneqsim/dependencies.yaml | head -1 | sed 's/version: "\(.*\)"/\1/')
+          echo "Current version (will become fallback): '$CURRENT_VERSION'"
+          echo "New version: '$NEQSIM_VERSION'"
+          
+          # Update the main version to the new version
+          sed -i 's/version: "[^"]*"/version: "'"$NEQSIM_VERSION"'"/' jneqsim/dependencies.yaml
+          
+          # Set fallback version to the previous version (current before update)
+          sed -i 's/fallback_version: "[^"]*"/fallback_version: "'"$CURRENT_VERSION"'"/' jneqsim/dependencies.yaml
+          
+          echo "Updated dependencies.yaml:"
+          grep -A 10 -B 5 "version:" jneqsim/dependencies.yaml
+
       - name: Bump version
         run: |
           VERSION="${{ inputs.pypi_version || inputs.version }}"

.github/workflows/tests.yaml

@@ -66,7 +66,7 @@ jobs:
     needs: build
     strategy:
       matrix:
-        java: [ '11', '17', '21' ]
+        java: [ '8', '11', '21' ]
     name: Java ${{ matrix.Java }}
     steps:
       - uses: actions/checkout@v4

README.md

@@ -49,6 +49,40 @@ def pressurize_gas():
 
 - [jpype](https://jpype.readthedocs.io/en/latest/index.html#)
 
+## Version Management
+
+jneqsim uses a controlled release process to ensure compatibility:
+
+- **Pinned Versions**: Each jneqsim release is pinned to a specific, tested NeqSim JAR version
+- **Automated Updates**: The nightly CI workflow automatically checks for new NeqSim releases and publishes updated jneqsim packages when available
+- **No Auto-Updates**: Applications using jneqsim will not automatically download newer NeqSim versions - they use the tested version that comes with their installed jneqsim package
+- **Cache Management**: Downloaded JARs are cached locally in `~/.jneqsim/cache` for faster subsequent usage
+
+## Development
+
+### Running Tests
+
+Quick testing options:
+
+```bash
+# Install test dependencies
+pip install pytest pytest-mock
+
+# Run unit tests (fast)
+make test-unit
+# or: pytest -v -m "not slow" tests/
+
+# Run all tests (may download JARs)
+make test-all  
+# or: pytest -v tests/
+
+# Run with coverage
+make coverage
+# or: pytest --cov=jneqsim --cov-report=html tests/
+```
+
+See [TESTING.md](TESTING.md) for detailed testing documentation.
+
 
 <a id="Contributing"></a>
 

jneqsim/dependencies.yaml

@@ -2,8 +2,14 @@
 # This file defines how to resolve NeqSim Java dependencies
 
 neqsim:
-  # Version to use ("latest" or specific version like "2.5.25")
-  version: "latest"
+  # Version to use (specific version that has been tested with this jneqsim release)
+  # This version is automatically updated by the CI/CD pipeline when a new NeqSim release is published
+  version: "3.0.43"
+  
+  # Fallback version when GitHub API is unavailable (rate limited, network issues)
+  # This should be the previous tested version, providing a safety fallback mechanism
+  # The CI/CD pipeline automatically sets this to the previous version when updating
+  fallback_version: "3.0.42"
 
   # GitHub Releases source
   sources:
@@ -17,10 +23,14 @@ neqsim:
       assets:
         java8: "neqsim-{version}-Java8.jar"
         java11: "neqsim-{version}.jar"  # Default Java 11+ version
-        java17: "neqsim-{version}-Java17.jar"
         java21: "neqsim-{version}-Java21.jar"
 
 # Logging configuration
 logging:
   level: "INFO"  # DEBUG, INFO, WARNING, ERROR
-  show_progress: true
+  show_progress: true
+
+cache:
+  enabled: true
+  verify_integrity: true
+  # Cache stores one JAR file per version/Java version combination

jneqsim/dependency_manager.py

@@ -4,33 +4,43 @@
 Handles resolution and downloading of NeqSim Java dependencies from GitHub releases.
 """
 
-import json
 import logging
 import urllib.error
 import urllib.request
 from pathlib import Path
 from typing import Optional
-from urllib.parse import urlparse
 
 import yaml
 
+from .jar_cache import JARCacheManager
+
 
 class NeqSimDependencyManager:
     """Manages NeqSim JAR dependencies from GitHub releases"""
 
-    def __init__(self, config_path: Optional[Path] = None):
+    def __init__(self, config_path: Optional[Path] = None, cache_dir: Optional[Path] = None):
         """
         Initialize dependency manager
 
         Args:
             config_path: Path to dependencies.yaml, defaults to package config
+            cache_dir: Directory for caching version info, defaults to ~/.jneqsim/cache
         """
         if config_path is None:
             config_path = Path(__file__).parent / "dependencies.yaml"
 
+        if cache_dir is None:
+            cache_dir = Path.home() / ".jneqsim" / "cache"
+
+        self.cache_dir = cache_dir
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
         self.config = self._load_config(config_path)
         self.logger = self._setup_logging()
 
+        # Initialize cache manager
+        self.cache_manager = JARCacheManager(self.cache_dir, self.config, self.logger)
+
     def _load_config(self, config_path: Path) -> dict:
         """Load configuration from YAML file"""
         with open(config_path) as f:
@@ -50,43 +60,6 @@ def _setup_logging(self) -> logging.Logger:
 
         return logger
 
-    def _validate_url(self, url: str, allowed_hosts: set[str]) -> None:
-        """
-        Validate URL for security - ensures HTTPS and trusted hosts only
-
-        Args:
-            url: URL to validate
-            allowed_hosts: Set of allowed hostnames
-
-        Raises:
-            ValueError: If URL is invalid or from untrusted host
-        """
-        parsed = urlparse(url)
-
-        if parsed.scheme != "https":
-            raise ValueError(f"Only HTTPS URLs are allowed, got: {parsed.scheme}")
-
-        if parsed.hostname not in allowed_hosts:
-            raise ValueError(f"Untrusted host: {parsed.hostname}. Allowed hosts: {allowed_hosts}")
-
-    def get_latest_version(self) -> str:
-        """Get latest NeqSim version from GitHub API"""
-        repo = self.config["neqsim"]["sources"]["github"]["repository"]
-        url = f"https://api.github.com/repos/{repo}/releases/latest"
-
-        # Validate URL for security
-        self._validate_url(url, {"api.github.com"})
-
-        try:
-            with urllib.request.urlopen(url) as response:  # noqa: S310
-                data = json.loads(response.read())
-                version = data["tag_name"].lstrip("v")
-                self.logger.debug(f"Latest version: {version}")
-                return version
-        except Exception as e:
-            self.logger.error(f"Failed to get latest version: {e}")
-            raise RuntimeError(f"Could not determine latest NeqSim version: {e}") from e
-
     def _get_jar_patterns(self, java_version: int) -> list[str]:
         """Get list of JAR filename patterns to try for a given Java version.
 
@@ -101,40 +74,41 @@ def _get_jar_patterns(self, java_version: int) -> list[str]:
                 github_config["assets"]["java8"],  # Standard pattern
                 github_config["assets"]["java11"],  # Fallback
             ]
-        elif java_version >= 21:
+        elif 11 <= java_version < 21:
             return [
-                "neqsim-{version}-Java21-Java21.jar",  # Newer pattern
-                github_config["assets"]["java21"],  # Standard pattern
+                "neqsim-{version}.jar",  # Standard pattern
                 github_config["assets"]["java11"],  # Fallback to default
             ]
-        elif java_version >= 17:
+        elif java_version >= 21:
             return [
-                "neqsim-{version}-Java17-Java17.jar",  # Newer pattern
-                "neqsim-{version}-Java17.jar",  # Standard pattern
+                "neqsim-{version}-Java21-Java21.jar",  # Newer pattern
+                github_config["assets"]["java21"],  # Standard pattern
                 github_config["assets"]["java11"],  # Fallback to default
             ]
         else:
             return [github_config["assets"]["java11"]]
 
-    def _get_from_github(self, version: str, java_version: int) -> Path:
-        """Download JAR from GitHub releases with fallback support"""
+    def _get_JAR_from_github(self, version: str, java_version: int) -> Path:
+        """Download JAR from GitHub releases with fallback support and caching"""
         github_config = self.config["neqsim"]["sources"]["github"]
-        patterns_to_try = self._get_jar_patterns(java_version)
 
-        # Create temporary directory for download
-        import tempfile
+        # Check cache first
+        cached_jar = self.cache_manager.get_cached_jar(version, java_version)
+        if cached_jar:
+            return cached_jar
 
-        temp_dir = Path(tempfile.mkdtemp(prefix="jneqsim_"))
+        patterns_to_try = self._get_jar_patterns(java_version)
 
         # Try each pattern until one succeeds
         last_error = None
         for i, asset_pattern in enumerate(patterns_to_try):
             jar_filename = asset_pattern.format(version=version)
             url = f"{github_config['base_url']}/v{version}/{jar_filename}"
 
-            # Validate URL for security
-            self._validate_url(url, {"github.com"})
+            # Create temporary directory for download
+            import tempfile
 
+            temp_dir = Path(tempfile.mkdtemp(prefix="jneqsim_"))
             downloaded_jar = temp_dir / jar_filename
 
             try:
@@ -158,7 +132,9 @@ def _get_from_github(self, version: str, java_version: int) -> Path:
                 else:
                     self.logger.info(f"Downloaded from GitHub: {downloaded_jar.name}")
 
-                return downloaded_jar
+                # Cache the downloaded JAR
+                cached_jar = self.cache_manager.cache_jar(downloaded_jar, version, java_version)
+                return cached_jar
 
             except urllib.error.HTTPError as e:
                 if e.code == 404:
@@ -180,38 +156,31 @@ def _get_from_github(self, version: str, java_version: int) -> Path:
         self.logger.error(error_msg)
         raise RuntimeError(error_msg) from last_error
 
-    def resolve_dependency(self, version: Optional[str] = None, java_version: Optional[int] = None) -> Path:
+    def resolve_dependency(self, java_version: Optional[int] = None) -> Path:
         """
         Resolve NeqSim dependency
 
         Args:
-            version: NeqSim version, defaults to config or latest
+            version: Specific NeqSim version to use. If None, uses the version
+                    configured in dependencies.yaml. Note: The config should specify
+                    a pinned version that has been tested with this jneqsim release.
             java_version: Java version, auto-detected if None
 
         Returns:
             Path to resolved JAR file
         """
-        # Determine version and java version
-        version = self._resolve_version(version)
+
+        neqsim_version = self.config["neqsim"]["version"]
+        if neqsim_version is None:
+            raise ValueError("NeqSim version must be specified either as an argument or in dependencies.yaml")
+
         java_version = self._resolve_java_version(java_version)
 
         # Download dependency
-        jar_path = self._get_from_github(version, java_version)
+        jar_path = self._get_JAR_from_github(neqsim_version, java_version)
 
         return jar_path
 
-    def _resolve_version(self, version: Optional[str]) -> str:
-        """Resolve the NeqSim version to use"""
-        if version is None:
-            version = self.config["neqsim"]["version"]
-            if version == "latest":
-                version = self.get_latest_version()
-
-        if version is None:
-            raise RuntimeError("Could not determine NeqSim version")
-
-        return version
-
     def _resolve_java_version(self, java_version: Optional[int]) -> int:
         """Resolve the Java version to use"""
         if java_version is not None:
@@ -226,3 +195,8 @@ def _resolve_java_version(self, java_version: Optional[int]) -> int:
                 return 11  # Default fallback
         except ImportError:
             return 11  # Default fallback
+
+    @property
+    def jar_cache_dir(self) -> Path:
+        """Access to JAR cache directory for backward compatibility"""
+        return self.cache_manager.jar_cache_dir