9.0.0

RESTHeart 9.0.0 Release Notes

We're excited to announce RESTHeart 9.0, a fantastic release packed with new features and significant performance improvements. This major version brings enhanced security controls, modern authentication capabilities, and optimized runtime performance to help you build faster and more secure MongoDB APIs.

Highlights

• Java 25 LTS required
• New OAuth 2.0-style authentication endpoints (/token, /token/cookie) with 85% performance improvement
• Enhanced authorization with request body predicates and query parameter access
• Aggregation pipeline security blocks dangerous operations ($out, $merge, JavaScript execution)
• GraalVM-based Docker images with improved startup time and memory usage
• Enhanced observability with distributed tracing and custom metrics support

Breaking Changes

• Map-Reduce pipelines removed - migrate to aggregation pipelines
• Docker images switched from OpenJDK to GraalVM
• GraphQL descriptors: remove descriptor.name, use string _id values
• Token authentication: update clients to use /token endpoints

Upgrade Guide

See the full upgrade documentation: https://restheart.org/docs/foundations/upgrade-to-v9

---

Release Date: 2026-01-15

8.13.1

Release Notes – Version 8.13.1

Release Date: 2025-12-18

Bug Fixes

• PingService: Fixed response status code to always return 200 OK. (960eab0)
• Client Connection: Now handles client connection closure as 400 Bad Request instead of 500 Internal Server Error. (ee1c867)

Dependency Updates

• logback-classic: Updated to version 1.5.22. (f7e545b)

---

Full Changelog: 8.13.0...8.13.1

8.13.0

Release Notes - RESTHeart 8.13.0

This is a minor release to mainly fix bugs in the native image generation.

Enhancements 🚀

Improved --fork startup option implementation - Updated to use Process API for better process management (#548)

Bug Fixes 🐛

Native Image Build

• Fixed native image build by adding explicit PluginsClassloader initialization
• Ensured ca-certificates installation and proper cleanup in Dockerfile.native
• Added ping message to environment variable in Dockerfile.native
• Updated artifact download path in native image workflows

Dependencies 📦

• MongoDB: Updated to version 8.0 in Docker Compose files

Technical Changes 🔧

• Native image configuration updates (proxy-config.json, reflect-config.json)
• Bootstrapper and Shutdowner improvements
• PluginsRegistryImpl enhancements
• FileUtils and RESTHeartDaemon refactoring

---

Full Changelog: 8.12.0...8.13.0

8.12.0

RESTHeart 8.12.0 Release Notes

Release Date: November 24, 2025

Overview

RESTHeart 8.12.0 includes important bug fixes for MongoDB 8.0.16+ compatibility, HAL response serialization, query cache functionality, and dependency updates for improved security and performance.

---

🐛 Bug Fixes

MongoDB 8.0.16+ Transaction Compatibility

Issue: Karate integration test sessions.feature:40 failing with MongoDB 8.0.16+ due to changed transaction error message format.

Root Cause: MongoDB 8.0.16 introduced SERVER-91503 which changed transaction error messages to include session ID information for better debugging. The new format "1 on session <uuid> - <hash> - - using txnRetryCounter 0" was not recognized by RESTHeart's transaction number extraction logic, causing NumberFormatException.

Fix: Updated TxnsUtils.removeWithTxnNumber() to detect and parse the MongoDB 8.0.16+ error format while maintaining full backward compatibility with all previous MongoDB versions (5.x, 6.x, 7.x, 8.0.0-8.0.15).

Files Changed:

• mongodb/src/main/java/org/restheart/mongodb/db/sessions/TxnsUtils.java
• mongodb/src/test/java/org/restheart/mongodb/db/sessions/TxnsUtilsTest.java

Related:

• SERVER-91503 - Improve NoSuchTransaction error message for transactions
• Issue ##579 - Karate integration test sessions.feature:40 failing with MongoDB 8.0 (works fine with 7.0 and 6.0)

---

HAL Response Empty String Serialization (Issue #578)

Issue: Empty string fields in MongoDB documents were inconsistently returned as null in HAL (Hypertext Application Language) format responses instead of their actual empty string value "".

Root Cause: The BsonUtils.toJson() method left trailing whitespace when serializing BSON string values. MongoDB's JSON serialization produces formatted output like {"x" : ""} with spaces around the colon. After removing the structural JSON characters, a leading space remained (" ""), causing empty strings to be misrepresented.

Fix: Added .strip() call in BsonUtils.toJson() method (line 760) to remove leading and trailing whitespace from the final string representation.

Impact:

• Fixes inconsistent HAL response behavior for documents with empty string fields
• Ensures data integrity between MongoDB storage and REST API responses
• No breaking changes - only fixes incorrect null representation

Files Changed:

• commons/src/main/java/org/restheart/utils/BsonUtils.java
• commons/src/test/java/org/restheart/utils/BsonUtilsTest.java

Related: GitHub Issue #578

---

Query Cache Not Working (Issue #575)

Issue: The ?cache query parameter was not working correctly after MongoDB driver updates, causing performance degradation for repeated queries.

Fix: Refactored Collections.java and GetCollectionCache.java to properly handle collection caching with the updated MongoDB driver internals. Added comprehensive integration tests in MongoDriverInternalsIT.java to verify cache functionality.

Files Changed:

• mongodb/src/main/java/org/restheart/mongodb/db/Collections.java
• mongodb/src/main/java/org/restheart/mongodb/db/GetCollectionCache.java
• test-integration/src/test/java/org/restheart/test/integration/MongoDriverInternalsIT.java

Related: GitHub Issue #575

---

🔧 Improvements

Enhanced Whitespace Handling

Refactored PingService and MetricsService to replace trim() with strip() for improved whitespace handling, consistent with modern Java best practices and Unicode support.

Files Changed:

• core/src/main/java/org/restheart/handlers/PingService.java
• metrics/src/main/java/org/restheart/metrics/MetricsService.java

---

Code Quality Improvements

• RequestDispatcherHandler: Refactored for improved readability and maintainability
• MongoDriverInternalsIT: Fixed test reliability issues

---

📦 Dependency Updates

• jboss-threads: Updated to 3.9.2 (security and performance improvements)
• logback-classic: Updated to 1.5.21 (latest stable release with bug fixes)

---

🧪 Testing

New Test Coverage

• Added testToJsonEmptyString() and testToJsonDocumentWithEmptyString() in BsonUtilsTest (23 total tests)
• Added testRemoveWithTxnNumberMongo8() in TxnsUtilsTest (5 total tests)
• Added comprehensive integration tests in MongoDriverInternalsIT for cache functionality

Test Results

✅ All 149 tests pass across all modules:

• commons
• security
• mongodb
• graphql
• metrics
• core
• test-plugins
• polyglot

---

🔄 Backward Compatibility

MongoDB Transaction Format Support

RESTHeart 8.12.0 maintains full backward compatibility with all MongoDB transaction error formats:

• MongoDB <5: with txnNumber 10
• MongoDB 5: with { txnNumber: 10 }
• MongoDB 6/7: with txnNumberAndRetryCounter { txnNumber: 10, txnRetryCounter: 0 }
• MongoDB 8.0.0-8.0.15: 1 using txnRetryCounter 0
• MongoDB 8.0.16+: 1 on session <uuid> - <hash> - - using txnRetryCounter 0

---

📋 Upgrade Notes

This is a recommended update for all users, especially those:

• Running MongoDB 8.0.16 or later
• Using HAL responses with empty string fields
• Experiencing cache-related performance issues

No configuration changes or data migration required.

---

🔗 Links

• GitHub Release
• Issue #578 - HAL Empty String Bug
• Issue ##579 - Karate integration test sessions.feature:40 failing with MongoDB 8.0 (works fine with 7.0 and 6.0)
• Issue #575 - Cache Not Working
• MongoDB SERVER-91503

---

Full Changelog: 8.11.0...8.12.0

8.11.0

RestHeart 8.11.0

This minor release introduces a new lightweight database connectivity probe (the primary user-facing feature), several build and native-image improvements, a small dependency bump, and minor documentation/visibility cleanups.

Highlights — DbProbeService (new readiness probe)

The main feature in 8.11.0 is the new DbProbeService plugin (registered as database-probe) which exposes a lightweight health/readiness endpoint at:

GET /health/db

Motivation

The /ping service tests if RESTHeart process is up and running, but it does not touch the database.

Purpose and contract

• Intended for readiness checks only. The probe performs a safe, non-destructive MongoDB ping using db.runCommand({ ping: 1 }) and therefore does not write any data.
• Cheap and concurrent: implemented to be low-overhead so it can be used by load balancers, Kubernetes readiness/liveness probes, or other monitoring systems.

Response shape (JSON)

• Successful ping (HTTP 200)

{ "status": "ok", "db": "admin", "pingMs": 24 }

• Failure examples

  • Too many concurrent probes (HTTP 429)

  { "status": "fail", "error": "too many concurrent probes", "pingMs": 5 }

  • Ping timeout (HTTP 504)

  { "status": "fail", "error": "ping timeout", "pingMs": 2000 }

  • Execution/connection error (HTTP 503)

  { "status": "fail", "error": "<cause message>", "pingMs": 10 }

Configuration example

You can provide the timeout-ms and dbname values via the plugin config map. Example plugin configuration snippet (YAML):

database-probe:
  enabled: true
  # how long to wait for the ping before timing out (ms)
  timeout-ms: 2000
  # database name to run the ping against
  dbname: admin

Usage examples

• Quick curl to check readiness:

curl -sS -f http://localhost:8080/health/db || echo "unhealthy"

Other changes in this release

• Build / native-image

  • Native-image related updates: native-image.properties and pom.xml updated to improve compatibility and exclude problematic config (--exclude-config wildfly-common-.*.jar).

• Dependency

  • caffeine bumped from 3.2.2 -> 3.2.3 (minor patch update).

---

Full Changelog: 8.10.1...8.11.0

8.10.1

RESTHeart 8.10.1 Release Notes

Release Date: October 22, 2025

🔧 Bug Fixes

Docker Container JVM Configuration

🐛 Fixed critical JVM startup issues in Docker containers caused by experimental G1GC flags that required explicit unlocking in JDK 24.

Changes:

• Removed experimental flags G1NewSizePercent and G1MaxNewSizePercent that were causing startup failures
• Removed redundant default flags G1ReservePercent and InitiatingHeapOccupancyPercent
• Simplified JVM configuration to use only meaningful performance tuning flags

Impact: Version 8.10.0 Docker containers failed to start with the error:

Error: VM option 'G1NewSizePercent' is experimental and must be enabled via -XX:+UnlockExperimentalVMOptions.

Affected Images:

• softinstigate/restheart:8.10.0
• softinstigate/restheart:8.10.0-distroless
• softinstigate/restheart:8.10.0-graalvm

⚠️ Users running 8.10.0 containers should upgrade to 8.10.1 immediately.

Final JVM Configuration

All Docker images now use this optimized, production-ready JVM configuration:

java \
    -Dfile.encoding=UTF-8 \
    -server \
    -XX:+UseG1GC \
    -XX:MaxGCPauseMillis=50 \
    -XX:MaxRAMPercentage=80.0 \
    -XX:InitialRAMPercentage=50.0 \
    -XX:+DisableExplicitGC \
    -XX:+UseStringDeduplication \
    -Djdk.tracePinnedThreads=full \
    -XX:+ExitOnOutOfMemoryError \
    -jar restheart.jar

Key flags:

• MaxGCPauseMillis=50 - Targets 50ms GC pauses for low-latency REST API responses
• MaxRAMPercentage=80.0 - Uses 80% of container memory for heap
• InitialRAMPercentage=50.0 - Starts with 50% heap allocation
• UseStringDeduplication - Reduces memory footprint for duplicate strings
• ExitOnOutOfMemoryError - Enables Kubernetes/container orchestration to restart on OOM

📦 Distribution

All artifacts are available on:

• Docker Hub: softinstigate/restheart:8.10.1
• Maven Central: org.restheart:restheart:8.10.1
• GitHub Releases: https://github.com/SoftInstigate/restheart/releases/tag/8.10.1

🔄 Migration Guide

From 8.10.0

Simply update your image tag:

# Docker
docker pull softinstigate/restheart:8.10.1

# Docker Compose
# Update docker-compose.yml
image: softinstigate/restheart:8.10.1

# Kubernetes
# Update deployment.yaml
image: softinstigate/restheart:8.10.1

No configuration changes required - this is a drop-in replacement.

From 8.9.x or earlier

No breaking changes. Update image tag as shown above.

---

Full Changelog: 8.10.0...8.10.1

8.10.0

RESTHeart 8.10.0 Release Notes

Release Date: October 20, 2025

⚠️ Note: Version 8.10.0 Docker containers have incorrect JVM flags that prevent startup.
Please use 8.10.1 or later if using official docker images.

🎉 What's New in 8.10.0

Java 24 Upgrade

RESTHeart 8.10.0 is now built with Java 24 (JDK 24 from Eclipse Temurin), bringing the latest performance improvements, security updates, and language features to the framework.

Key Benefits

• ✅ Enhanced Virtual Threads performance and stability
• ✅ Latest security patches and bug fixes
• ✅ Improved G1GC performance for REST API workloads
• ✅ Better memory management and reduced latency

Docker Image Improvements

1. Chainguard Distroless Image 🔒

The distroless Docker image now uses Chainguard's minimal JRE image (cgr.dev/chainguard/jre:latest) instead of Google's distroless. This was necessary because Google is very late in publishing the newest JREs:

• Smaller attack surface: Wolfi-based minimal runtime
• Faster security updates: Chainguard provides more frequent updates
• Better maintained: Active development and support
• Java 25 ready: Chainguard already provides Java 25 images

Note: The distroless image now supports only linux/amd64 and linux/arm64 platforms (removed linux/ppc64le due to Chainguard image limitations). We might revert back to Google's distroless in the future, when they'll publish updated images.

2. GraalVM Update

Updated to GraalVM 24.0.2-graalce for improved polyglot support and native image capabilities.

3. Optimized G1GC Configuration

All Docker images now include production-tuned G1GC settings optimized for RESTHeart's REST API workload characteristics:

-XX:+UseG1GC
-XX:MaxGCPauseMillis=50
-XX:G1NewSizePercent=30
-XX:G1MaxNewSizePercent=60
-XX:G1ReservePercent=10
-XX:InitiatingHeapOccupancyPercent=45
-XX:MaxRAMPercentage=80.0
-XX:InitialRAMPercentage=50.0
-XX:+UseStringDeduplication

These settings are optimized for:

• High-throughput REST APIs
• Small heap sizes (≤2GB)
• Many concurrent clients
• Short-lived request objects
• Virtual Threads workloads

Documentation Updates

• Updated all documentation references from Java 21 to Java 24
• Added comprehensive GC selection guide (GC-SELECTION-GUIDE.md)
• Updated GraalVM documentation with Java 24 instructions
• Refreshed example project documentation

📦 Docker Images

All Docker images are available on Docker Hub:

• Standard: softinstigate/restheart:8.10.0
• Distroless: softinstigate/restheart:8.10.0-distroless (Chainguard-based)
• GraalVM: softinstigate/restheart:8.10.0-graalvm

Multi-Platform Support

• Standard & GraalVM images: linux/amd64, linux/arm64, linux/ppc64le
• Distroless image: linux/amd64, linux/arm64

🔧 Technical Changes

Build System

• Updated all Maven POMs to Java 24
• Updated GitHub Actions workflows to use JDK 24
• Removed obsolete JDK 21 references

CI/CD

• All workflows now use actions/setup-java@v4 with Temurin 24
• Native image builds updated to GraalVM 24.0.2
• Docker builds optimized for multi-platform support

⚠️ Breaking Changes

None. This release is fully backward compatible with RESTHeart 8.9.x.

Issues

There was an error generating native binary images, but you can safely use those from v. 8.9.0 as this release does not add any new functionality.

📝 Migration Guide

From 8.9.x to 8.10.0

1. Update Docker images (if using Docker):

   docker pull softinstigate/restheart:8.10.0

2. Update Java version (if building from source):

   • Ensure you have JDK 24 installed
   • Update JAVA_HOME environment variable

3. Review JVM options:

   • The optimized G1GC settings are now default in Docker images
   • If running outside Docker, consider applying the same settings for optimal performance

Distroless Image Users

If you're using the distroless image on ppc64le, you'll need to switch to either:

• The standard image: softinstigate/restheart:8.10.0
• The GraalVM image: softinstigate/restheart:8.10.0-graalvm

Both still support linux/ppc64le platform.

🐛 Bug Fixes

• Fixed GraalVM Dockerfile syntax error (removed double quote in ENTRYPOINT)
• Improved Docker build reliability across all platforms

📚 Resources

• Documentation: https://restheart.org/docs
• Docker Hub: https://hub.docker.com/r/softinstigate/restheart
• GitHub: https://github.com/SoftInstigate/restheart
• Website: https://restheart.org

🔗 Full Changelog

8.9.0...8.10.0

8.9.0

RESTHeart 8.9.0 – Release Notes

Release date: October 15, 2025

Features & Improvements

• 🐛 MetricsService: Added configurable status code for missing metrics registry. By default, RESTHeart returns HTTP 404 for non-existent registries (legacy behavior), but you can now set missing-registry-status-code: 200 in the metrics configuration to return HTTP 200 with an empty body for better Prometheus compatibility. Ref: https://restheart.org/docs/monitoring#handling-missing-metrics-registries
• 🐛 MetricsService: When a metrics registry does not exist, the service now returns an empty body instead of a 404 error, improving compatibility with Prometheus and other metrics scrapers.
• 🐛 PingService: Enhanced proxy support. The getHostHeader method now correctly handles the X-Forwarded-Host header, returning the appropriate value even with multiple proxies.
• 🔧 Dependencies: Updated Maven dependencies and plugins to the latest versions.
• 🔧 Build Optimization: Added parallel execution flag for native image builds, speeding up the build process.
• 🔧 CI/CD: Increased the timeout for the build-and-upload job from 20 to 25 minutes.
• 🔧 Workflow: Updated native image release workflow reference to use local path.

Minor Updates

• No breaking changes to public APIs.
• Improved internal documentation and service configurability.

Full Changelog: 8.8.1...8.9.0

8.8.1

Release Notes - RESTHeart 8.8.1

🐛 Bug Fixes

• Fixed PATCH request error with update operator expressions: Resolved an error that occurred when using PATCH requests with update operator expressions in combination with permissions that apply mongo.mergeRequest #503

• Fixed rootRoleGuard error handling: Corrected an issue where the rootRoleGuard would throw an error when the root role is disabled (set to null)

✨ Features & Improvements

• Enhanced request interface support: BsonRequest and MongoRequest now properly honour the RawBodyAccessor interface, providing better access to raw request body data

🔧 Internal Changes

• Minor refactoring improvements in change stream classes
• Updated .gitignore configuration

---

Full Changelog: [8.8.0...8.8.1](https://github.com/your-repo/compare/8.8.0...8.8.1)

8.8.0

Release Notes - RESTHeart 8.8.0

✨ New Features

Logging Enhancements

• No-colors option: Added no-colors configuration option to disable ANSI color output in logging, improving compatibility with CI/CD pipelines and environments that don't support colored output (#562)

🐛 Bug Fixes

• RequestLogger race condition: Fixed race condition in RequestLogger when handling excluded requests, improving logging reliability

🔧 Configuration Updates

• Updated template configuration files to include new request logging exclusion options